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Preface 
Conventions Used in Tliis IVIanual 

Throughout the A/UX manuals, words that must be typed exactly as 
shown or that would actually appear on the screen are in Courier 
type. Words that you must replace with actual values appear in italics 
(for example, user-name might have an actual value of j oe). Key 
names appear in Caps (for example. Return). Special terms are in 
bold type when they are introduced; many of these terms are also 
defined in the glossary in the A/UX System Overview. 

Syntax notation 

All A/UX manuals use the following conventions to represent 
command syntax. A typical AAJX command has the form 

command [flag-option] [argument] . . . 

where: 

Command name (the name of an executable file). 



command 
flag-option 



argument 



One or more flag options. Historically, flag options 
have the form 

-[opt...] 

where opt is a letter representing an option. The 
form of flag options varies from program to 
program. Note that with respect to flag options, the 
notation 

[-a][-b][-c] 

means you can select one or more letters from the 
list enclosed in brackets. If you select more than one 
letter you use only one hyphen, for example, -ab. 

Represents an argument to the command, in this 
context usually a filename or symbols representing 
one or more filenames. 



[ ] Surround an optional item. 

Follows an argument that may be repeated any 
number of times. 

Courier type any where in the syntax diagram indicates that 
characters must be typed literally as shown. 

italics for an argument name indicates that a value must be 

supplied for that argument. 

Other conventions used in this manual are: 

<CR> indicates that the Return key must be pressed. 

"jc An abbreviation for Control-jc, where x may be 

any key. 

cmd{sect) A cross-reference to an AAJX reference manual. 

cmd is the name of a command, program, or other 
facility, and sect is the section number where the 
entry resides. For example, cat(l). 
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Chapter 1 
Introduction to A/UX Text Processing 



1. A/UX text formatting tools: A brief overview 

The AAJX operating system provides a large number of tools for 
editing, formatting, and printing text and graphics. You can use these 
tools to prepare almost any kind or size of document, from newsletters 
to books. This chapter is a general introduction to AAJX text 
processing. 

To understand the A/UX text processing tools, it is helpful to 
understand the process involved in producing a final printed document. 
The sequence typically looks something like that in Figure 1-1. 

Figure 1-1. Producing a printed document 
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It is a basic assumption of the AAJX text processing system that these 
tasks are separable from one another and ought to be handled by 
different programs. First, you use one of the standard A/UX editors to 
enter and edit your text. The editor doesn't format or print the file; it 
merely stores your text, exactiy as you enter it. To arrange the text into 
pages and paragraphs, you use a formatting program (usually troff 
or nrof f in conjunction with a macro package). These programs use 
instructions you have entered in the text file, which indicate how you 
want the final output to look. Once the text is edited and formatted, 
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you may print the document by directing the fonnatted output to a 
printer. 

1.1 Formatting text: troff and nroff 

The AAJX text processing system is based on a pair of programs called 
troff and nroff. troff formats its input for printing on any 
high-resolution typesetter or laser printer that is capable of printing 
multiple fonts and type sizes, nroff formats its input for printing on 
less-capable devices such as daisy wheel and dot matrix printers, or 
your terminal screen, troff and nroff are for the most part 
compatible with each other, so that a single input file may be processed 
with either formatting program, nroff simply ignores any troff 
commands that the intended output device cannot support. From now 
on in this chapter, any reference to troff means either nroff or 
troff. 

As mentioned above, troff searches through your file for commands. 
Input consists of text, which will print, and commands, which set 
parameters or call out special characters. These are troff 
commands. There are two ways to call out a command: 

• Begin a line with a control character (period or single quote) 
optionally followed by a space or tab; followed by a one- or 
two-character command name; followed by a space or a newline. 
These are sometimes called "dot commands." The single quote 
suppresses the break function (the forced output of a partially 
filled line) caused by certain requests. Unrecognized command 
names are ignored. 

• Type an escape character (\), followed by a command name 
anywhere in a line. These are sometimes called "escape 
sequences." 

The following are examples of troff dot commands: 

.sp 4 

.ft B 

These instruct troff to leave four blank lines and switch into the bold 
font. 

The following is an example of a troff escape sequence: 
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The last word on this line is \s20big.\slO 
This command causes trof f to produce the following output: 



The last word on this line 



is big. 



The sequence \s2 instructs trof f to switch to point size 20. The 
same effect could be achieved using trof f dot commands, as follows: 

The last word on this line is 
.ps 20 
big. 
.ps 10 

1.2 Formatting text: The mm macro package 

trof f and nrof f provide facilities for controlling virtually all 
features affecting the appearance of the final printed page. These 
programs do so, however, at a relatively low level; for instance, neither 
program provides automatic margins, page headers and footers, or page 
numbering. To obtain these features, as well as countless others you 
will probably need, you must use a macro package in conjunction with 
trof f . A macro is a collection of trof f commands grouped into a 
useful unit, and a macro package is a collection of macros grouped 
into a useful unit. 

The standard AAJX macro package is called mm. (For a brief 
discussion of other macro packages, see "Other Macro Packages.") 
The mm package provides two kinds of additions to basic t rof f 
capabilities: 

• a large number of dot commands that are not included in the 
t rof f command set but are necessary for most document 
processing 

• default parameter settings governing margins, page length, 
paragraph indent levels, and so forth 

The mm dot commands are almost universally uppercase, to distinguish 
them from t rof f dot commands, which are all lowercase. For 
example, you can use 
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to indicate the beginning of a paragraph. You use these additional dot 
commands exactly like t rof f dot commands. However, when you 
run the file through the formatting program, trof f won't understand 
these macros unless you get it to read their definitions first. You can do 
this by invoking trof f with the -mm argument: 

trof f -mm file 

Thus, the argument to trof f gives you access to the mm macro 
package. You can get access to other macro packages in the same way. 

1.3 Formatting tables: tbi 

It's easy to produce tables in a document by using the program tbl. 
Here is an example of tbl output: 



Text processing programs 


Program 


Function 


eqn 


format equations 


grap 


format graphs 


IP 


printer spooler 


nrof f 


low-quality output 


pic 


format pictures 


tbl 


format tables 


troff 


high-quality output 


vi 


enter/edit text 



The tbl program, unlike the mm package, operates as a preprocessor 
to troff. tbl processes the input file containing table specifications 
before it is processed by trof f, as follows: 

tbl file I troff -mm 

This is because tbl translates the table specifications into troff 
commands, tbl recognizes these specifications when they occur 
between lines beginning with the commands . TS and . TE. For 
instance, the input for the table above looks like this in the text file: 
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.TS 

box center tab ( : ) ; 

c s 

c c 

lf7 1 . 

\f6Text Processing Programs\fR 

.sp .5 

\ f 6P rogram : Funct ion\ f R 

,sp .5 

eqn: format equations 

grap : format graphs 

lp:printer spooler 

nroff : low-quality output 

pic: format pictures 

tbl: format tables 

troff : high-quality output 

vi : enter /edit text 

.TE 

For a complete discussion of the tbl program, see Chapter 6, "tbl 
Reference." 

1.4 Formatting equations: eqn 

The AAJX text processing system also includes another troff 
preprocessor, eqn, that allows you to include mathematical equations 
and formulas in documents, eqn searches for equation specifications 
contained within . EQ and . EN pairs. For example, the input 

.EQ 

X + y = 4 sup 2 

.EN 

yields the output 
And the input 

.EQ 

int X sup 3 dx = { x sup 4 } over 4 + c 

.EN 

yields the output 
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jx^dx=^+c 



Like tbl, eqn is a preprocessor to t rof f . So the general command 
line looks like 

eqn file \ trof f -mm 

See Chapter 7, "eqn Reference," for further details. 

1.5 Formatting pictures: pic 

You may also produce simple line drawings in a document by using the 
pic program, yet another trof f preprocessor. You specify pictures 
by including their descriptions within .PS and . PE pairs. For 
example, if you include the following description in the input file 

.PS 
box; arrow; ellipse 

.PE 

and run trof f with the pic preprocessor 

pic file I troff -mm ... 
you get the picture shown in Figure 1-2. 

Figure 1-2. A simple picture 




You can draw more complicated (and useful) drawings as well, such as 
those in Figures 1-3 and 1-4. The descriptions of these pictures are 
much more complicated than the simple description of Figure 1-2, but a 
mildly experienced pic user should have no trouble producing such 
diagrams. 
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Figure 1-3. A more complicated picture 
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Figure 1-4. An even more complicated picture 
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Virtually all the figures in this AAJX documentation were produced 
using pic. See Chapter 8, "pic Reference," for a complete 
discussion of the pic language. 

1.6 Formatting graphs: grap 

In addition to tables, equations, and simple line drawings, it is also 
possible to include graphs in a document formatted with trof f . This 
is accomphshed by using the grap preprocessor. Here is an example 
of grap output 
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Figure 1-5. A graph 





sed 1 








vi 1 








grap | 








pic 1 






Text 


tbl 1 






processing 


eqn | 






programs 


neqn | 








troff 1 








nroff 1 








psdit 1 








Ip 1 



50000 



100000 



Program size (bytes) 



Like these other preprocessors, grap looks for a specification of how 
the graph should look and the data to be graphed. These are enclosed 
within , Gl and . G2 pairs, as follows: 

.01 

specification of graph 

.02 

grap, however, is a preprocessor for pic; this simply means that 
grap translates the specification of the graph into pic code, not 
directly into troff code. So, to get graphical output, your command 
line must look something like this one: 

grap file I pic I troff -mm 

Figure 1-6 shows another example of grap's capabiUties. It charts 
San Francisco 49er wide receiver Jerry Rice's total receiving yardage 
per game for each of the sixteen regular season NFL football games in 
1986. The height of the little football indicates the yardage, and the 
number inside the football indicates how many catches Rice made that 
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day. Finally, the number of little goalposts under the football indicates 
how many touchdowns Rice scored in the game. 

Figure 1-6. A more complicated graph 
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For further information, see Chapter 9, "grap Reference." 

1 .7 Other macro packages 

In addition to the imra macro package, there are other macro packages 
that you may run into on AAJX systems. Of particular note is the ms 
macro package (see Chapter 5, "ms Reference' '). This program 
provides most of the same functions provided by the mm package, but 
with different syntax. For instance, a left-adjusted paragraph is 
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indicated in ms with the macro 

.LP 

and in mm it is indicated with the macro 

.P 

For the most part, the page- and font-description concepts underlying 
the mm macros (described below) will carry over into any other 
common macro package. There are some mm macros, however, for 
which there is no simple equivalent in other packages. 

Another very common macro package is the man macro package. This 
collection of macros is intended for the special purpose of formatting 
manual pages as presented in AlUX Command Reference , AlUX 
Programmer' s Reference , and AlUX System Administrator s Reference . 
See man(5) in AlUX Programmer' s Reference for further details. 

2. Page layout concepts 

To get the most out of the A/UX text processing programs, you must 
have some grasp of the terms used to describe page layout. This 
section introduces you to the most important of these. Terms that are 
boldfaced are also defined in "Glossary of Text Processing Terms" at 
the end of this book. 

If you use the mm macro package in conjunction with t rof f , the page 
is divided into a number of separate regions, some of which you can 
print on and some of which you cannot. The parts of a page are 
illustrated in Figure 1-7. 



Introduction to A/UX Text Processing 1 -1 1 



Figure 1-7. Parts of a page 
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Top margin — 
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Maximum line length 



Bottom margin 
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Printable portion of page 

Generally, you cannot print on the entire physical page (typically a 
sheet of paper); the mm macros automatically generate margins on all 
four sides of the paper. You can, however, increase or reduce any of 
these margins independently of the others. In addition, the mm package 
automatically provides headers and footers (lines of text that are 
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printed on the top and bottom, respectively, of every page). For more 
detailed discussion of these points, see "Margins" and "Headers and 
Footers." 

2.1 Principal units of measurement 

Many t rof f and mm commands require a unit of measure as part of 
the command. For instance, you must specify the line length as some 
number of inches or centimeters, and so on. t rof f and mm 
understand both inches and centimeters, as well as a number of other 
units that are more familiar to printers. The following table lists the 
principal units of measurement 



Unit 


Abbreviation 


Equivalence 


inch 


i 




centimeter 


c 


2.54c = li 


pica 


P 


6P=li 


point 


P 


72p = li 


em 


m 


width of "m" in current font 


en 


n 


width of "n" in current font 



Of these units, only picas and points are likely to be unfamiliar to you. 
Points are used mostly to specify sizes of type (also called "point 
sizes"), and picas are often used for specifying line lengths and page 
lengths. For the most part, you can avoid picas, but it can be difj&cult to 
specify type sizes in any unit other than points. 

2.2 Line length 

The default line length using t rof f (with or without the mm macro 
package) is 6 inches. The maximum length of a line of text (or 
graphics) is the widest printable portion of the page, which is 
dependent on the capabiUties of the printer you are using. You may 
specify the output line length with the t rof f command . 11 followed 
by some measurement; for example, 

.11 7i 

gives you a line length of 7 inches. There is no single mm command to 
accomplish the same thing. There is a number register that controls the 
length of the line and the page header and footer. You can set this 
register as follows: 
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.nr W 7i 
See "Number Registers" for more information. 

2.3 Page length 

The length of the physical page depends on the printer you are using; 
usually you will be working with one of the standard page sizes (8.5 by 
1 1 inches, or A4). By default, the mm package assumes an 1 1-inch 
page, but you can alter the page length by setting the L number 
register: 

.nr L 9i 

The equivalent trof f command is 

.pi 9i 

Note that this page length includes the top and bottom (vertical) 
margins. You can increase the amount of space taken by these margins 
with the .VM macro: 

.VM 2 5 

This adds two vertical spaces to the top margin and five vertical spaces 
to the bottom margin. 

2.4 Paragraph types 

You can specify more than one type of paragraph in a document. The 
mm macro package provides one macro, . P , for specifying the 
beginning of a paragraph (there is generally no need to specify the end 
of a paragraph). The argument you add to this macro determines the 
type of the paragraph it is. For instance, the command 

.P 
provides a left-adjusted paragraph, and the command 

.P 1 

provides a paragraph with the first line indented from the margin. 

If there is no argument to the . P command, mm provides whatever you 
have selected as the default paragraph type. You select the default type 
with the command 
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.nr Pt n 
where the argument n is as follows: 

Argument Resulting default 

left adjusted 

1 indented 

2 indented, except 
after headings, lists, 
or displays 

2.5 Margins 

There are two horizontal margins, left and right, on every page. The 
left margin is also known as the page offset, and you can change it 
using the trof f command .po. The default is about 1 inch, but you 
can increase or decrease it. 

This command would be appropriate to center a 6-inch line of text on a 
piece of paper 8.5 inches wide: 

•po 1.25i 

You can change the right margin by changing the line length or the 
page offset. 

2.6 Adjusting and filling 

By default, trof f both fills and adjusts the text it formats. To fill text 
is to place as much text on a line as will fit, regardless of how the text 
occurs in the input file. One nice feature of trof f is that it fills 
automatically. This means you can type your text into a file in 
whatever way is easiest for you to edit subsequently (for instance, 
beginning all sentences on a new line), trof f may have to break a 
word in the middle to achieve a nice fit, but it will usually do this 
hyphenation in an intelligent manner. 

You can control whether or not filling occurs with the trof f 
commands .nf and .fi. For instance, the input 
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• nf 

This text should not be filled. 

So the output 

will be arranged just like 

the input . 

produces the following output: 

This text should not be filled. 
So the output 
will be arranged just like 
the input. 

You can turn filling back on with the , f i command. 

To adjust text is to place small amounts of space between words in a 
filled line so that the line of output text is exactly the current line 
length, t rof f automatically adjusts text, but you can turn adjustment 
off with the command 

.na 

You can turn adjustment back on with the command 

.ad 

2.7 Indentation 

Occasionally you need to indent some stretch of text to set it off from 
the surrounding text. You can do so with the trof f command . in. 
For instance, the input 

.P 

This line is not indented at all. 

.in .5i 

This line is indented .5 inch. 

. in li 

This line is indented 1 inch. 

.in +.5i 

This line is indented 1.5 inch. 

.in 

This line is not indented. 

produces the following output: 
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This line is not indented at all. 

This line is indented .5 inch. 

This line is indented 1 inch. 

This line is indented 1.5 inch. 
This line is not indented. 

Notice that you can supply both absolute and relative arguments here, 
and that an argument of zero (0) returns to the current left margin. The 
indent persists until you reset it, or until it gets reset automatically. 

2.8 Headers and footers 

A header is a line of text that is printed on the top of every page. 
Similarly, a footer is a line of text that is printed on the bottom of 
every page. (See Figure 1-7 for the location of these lines.) Each of 
these lines is further divided into a left part, a center part, and a right 
part. You can specify any of these six items independently of the 
others. Further, you can specify different headers and footers for odd 
and even pages. 

There are six mm macros affecting headers and footers: 



PH 


page header (all pages) 


OH 


odd header 


EH 


even header 


PF 


page footer (all pages) 


OF 


odd footer 


EF 


even footer 



Each of these macros takes the same kind of argument, a string 
surrounded by double quotes ("), with each of the three parts of the 
header or footer. For instance, we might specify a page header as 
follows: 

•PH "'Chapter 8'%' The Bill of Rights'" 

This header wUl appear on all pages. The left header will read 
"Chapter 8," the center header will be the page number, and the right 
header will read "The Bill of Rights." 

Note that mm interprets the percent sign specially in a header or footer 
specification; each time the header or footer is printed, it is replaced by 
the current page number. 
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If you want one of the three parts of the header or footer to be empty, 
just leave the appropriate field in the argument string empty. For 
instance, the following command will cause the page number to be 
printed at the top of each page: 



,PH 



u f r 5, r r 



If you need an apostrophe in the header or footer, you can change the 
delimiting character to anything you like, and mm will detect the change 
automatically. For instance, you might want the following header 
specification: 

.PH "@Chapter 7@%@Bill's Alibi@" 

You may specify a separate header or footer for odd and even pages. 
The following pair represents a very common way to handle headers: 

.OH "@Chapter 7@%@Bill's Alibi@" 
.EH "@Bill's Alibi@%@Chapter 7@" 

2.9 Centered text 

You can center a line of text on the page by using the t rof f dot 
command .ce. For example, 

.ce 

This line is centered. 

produces 

This line is centered. 

If you provide a numeric argument, the corresponding number of lines 
will be centered. For example, 

.ce 3 

This is the first centered line. 

This is the second centered line. 

This is the third and last centered line . 

produces 

This is the first centered line. 

This is the second centered line. 

This is the third and last centered line. 

Note that filling and adjusting are turned off for lines that are centered. 
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2.10 Footnotes 

You can include footnotes in a document by enclosing the text to be 
footnoted between . fs and . fe pairs.^ For example, 

.FS 

This is the text of a footnote . 

It is smaller than the main text, 

and placed at the bottom of the page. 

.FE 

If you need consecutively numbered footnotes, you should include the 
string \ *F at the appropriate spot in the text. For further details about 
footnotes and footnote formats, see Chapter 4, "mm Reference." 

2.11 Heading levels 

In addition to the grouping provided by the paragraph macros, mm 
provides several macros for grouping paragraphs into sections and for 
generating a table of contents listing sections and subsections. 

The primary macro for grouping paragraphs into sections is . H, for 
' 'heading level." A typical use of this macro might look like this: 

.H 1 "The Clues to the Murder" 

There was a broken window, 

and the maid heard a loud scream 

shortly before midnight. 

In addition. 

This indicates that a first-level heading is to be generated; mm 
automatically numbers these headings. If this is the fourth such macro 
in our text file, the output looks like this: 



1 . This is the text of a footnote. It is smaller than the main text, and placed at the bottom 
of the page. 



Introduction to A/UX Text Processing 1-19 



4. The Clues to the Murder 

There was a broken window, and the maid heard a loud 
scream shortly before midnight. In addition. 

There may also be subsections within first-level sections. These are 
indicated with a second-level heading: 

.H 2 "An Investigation of the Glass Shards" 

The mm package allows for up to seven levels of headings (rarely are 
this many needed in typical documents, however). In addition, there is 
a macro for generating unnumbered headings: 

.HU "Appendix A: Summary of Clues" 

Many features of these heading level macros can be adjusted to taste, 
such as the point size and font for each heading level and the amount of 
spacing from surrounding text. See Chapter 4, "mm Reference," for a 
complete list. 

3. Font description concepts 

t rof f is able to print in any font that is supported by the printer. 
nrof f can generally print in only one font, but depending upon the 
capabiUties of the printer you are using, nrof f may be able to 
simulate boldface by overstriking and italics by underlining. 

3.1 Type families: Changing fonts 

You can achieve a great deal of clarity in a document by selecting fonts 
that are appropriate for your purposes. A font is a collection of letters 
and characters unified by a distinctive pattern or "look." What fonts 
are available to you is dependent on how trof f has been configured, 
but typically at least the following three fonts are available: 

Times Roman ABCDEFGHIJKLMNOPQRSTUVWXYZ 

Times Roman italic ABCDEFGHIJKLMNOPQRSTUVWXYZ 
Times Roman bold ABCDEFGHIJKLMNOPQRSTUVWXYZ 

By default, text is printed in "plain" Times Roman, unless you change 
fonts. You may change fonts with either a dot command (. ft) or an 
in-line escape sequence (\f ), followed by a name of the font desired. 
The following two lines give identical output: 
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This is in Times Roman, 

.ft B 

and this is Times Roman bold 



This is in Times Roman, 

\fBand this is Times Roman bold. 

The output in either case is 

This is in Times Roman, and this is Times Roman bold. 

You can also use mm macros: 

itmi macro Effect 

. B bold 

. I italics 

. R roman 

Thus, the example above could be further rewritten as 

This is in Times Roman, 

.B 

and this is Times Roman bold. 

You can also replace font names altogether with numbers. For 
example, instead of \f B, you may write \f 3. Many people prefer the 
numbers because it is easier to pick out the escape sequence. Which 
numbers correspond to which fonts depends on how your printer and 
software have been configured. For example, systems using the 
TranScript t rof f -to-PostScript translator driving the Apple 
LaserWriter® have the following correspondence: 
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Number Font 



1 


Times Roman 


2 


Times Italic 


3 


Times Bold 


4 


Times Bold Italic 


5 


Helvetica 


6 


Helvetica Bold 


7 


Courier 


8 


Courier Bold 



3.2 Point Size 

t rof f can work with virtually any size text that the printer supports. 
The program is usually configured to allow you access to only a portion 
of those actually printable. A normal range is something like 2 point to 
80 point. Point size 2 is so small that it's unreadable. The following 
shows point size 80: 



80 



Appropriately configured, however, trof f can do things like the 
following, which is a Times Roman 2 at 432 points: 
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The default type size is 10 point. You may change point sizes in a 
variety of ways. Usually this is done with the . ps command: 

.ps 14 

This text is now in 14 point. 

This produces 

This text is now in 14 point. 

You may also use the in-line escape sequence \ s: 
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This is in 10 point, \sl4and. this is in 14\sO. 
produces 

This is in 10 point, and this is in 14. 

Notice that \ s returns to the previous type size, not size 0. 

Type size changes may also be specified relatively. For instance, you 
may rewrite the previous example as follows: 

This is in 10 point, \s+4and this is in 14\sO. 

3.3 Vertical spacing 

The vertical spacing between two lines of text is the distance from the 
base of the characters on one line of text to the base of the characters 
on the next Une. Normally, the vertical spacing is set to 12 points, 
which is enough to accommodate a 10-point character plus a small 
amount of white space between Unes. If you change point sizes, you 
must increase or decrease the vertical spacing accordingly. You can 
change the vertical spacing with the . vs command: 

• ps 20 
. vs 22 

Two different vertical spacing settings are illustrated as follows: 

Point Size 12 
Vertical spacing 14 Vertical spacing 16 

Four score and seven pour score and seven 

years ago, our fathers y^^rs ago, our fathers 

brought forth on this ^ ^^^^ ^^ ^^^^ 

continent a new nation... 

continent a new nation... 

A very common mistake is to increase the point size without increasing 
the vertical spacing. In such a case you usually end up with garbage; 
for example. 
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This IS 24-pqinttext. , 
aithe normal 1 2-poiht 
vertical SDacmg. ^ 



You can set both the point size and the vertical spacing at once with the 
mm macro .S. For instance, 

.S 24 26 

sets the point size to 24 points and the vertical spacing to 26 points. 

3.4 Character set 

The set of characters that you can print using t rof f depends on the 
abilities of the printer you are using. Generally, a character is 
accessible to t rof f if it is a member of some font that t rof f knows 
about. A trof f font typically includes the following characters: 

ABCDEFGHIJKLMNOPQRSTUYWXYZ 

abcdefghijklmnopqrstuvwxyz 
1234567890 

&.,:;"~!@#$%^*()- + ={ } []\l>< 

In addition, there may be other fonts known as "special" fonts. 
Originally these fonts were used for mathematical symbols not 
available on the standard Times Roman font, but a special font can 
contain any sort of characters or glyphs, A typical mathematical 
special font provides the following characters, which include a full 
Greek alphabet: 

ABEAEOreiKAMNOn^'PSTYnXHZ 
a(3^6e<|)Y9iK^|j,vo7i;\}/paT'0(oxr|^ 

^^ c'V-oo=><=>3j<A<=VG ' X—id 
+ -oc>=:>°_c"=)nV3V~- 

There are two standard ways to get one of these characters to print in a 
document. First, you can use a feature of the preprocessor eqn that 
allows in-line equations. In that case, you would use the eqn name of 
these symbols. For instance, we have seen that eqn translates the word 
int into the symbol J (appropriately scaled, of course). 
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A second way to get access to special font characters is to use their 
trof f name. A few of these are 

Input Output Name 



\(pl 


+ 


plus 


\(mi 


- 


minus 


\ (mu 


X 


multiplication 


\(sr 


V 


square root 


\(br 


1 


box rule 


\(ua 


t 


up arrow 


\{da 


i 


down arrow 


\(ci 


O 


circle 


\(! = 


^ 


not equal 


\(is 


J 


integral 



For a complete list, see Chapter 3, "nrof f /trof f Reference." 

3.5 Accents 

The mm macro package provides the ability to print accent marks over 
certain characters. To do this, you need to put the mm name of the 
accent mark after the letter you want accented. For example, the input 

re\*' sumeX*' 

produces the word "re'sume". The following accents are available: 

Input Output Name 

\ * '^ " grave accent 

\ * ' ' acute accent 

\ * *" " circumflex 

\*- ~ tilde 

\ * , , cedilla 

\ * : " umlaut (lowercase) 

\ * ; umlaut (uppercase) 
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3.6 Overstriking 

The trof f formatter provides one further way of generating 
characters that are not in its basic character set: overstriking two or 
more characters. The in-line escape sequence \o will overstrike 
whatever characters (up to nine) are enclosed within single quotes. For 
instance, the input 

\o'>/' 

produces ":;^". The \o sequence centers each character as it 
overstrikes them. If instead you want the characters lined up on their 
left sides, you could use the \ z escape sequence. This instructs 
trof f to print the following character but not to move to the right 
after printing it. For instance, the input 

\z>/ 

produces '>". 

4. Other formatting features 

trof f and the mm macro package provide several further features that 
are very useful in document production: displays, automatic list and 
table of contents generation, multicolumn output, strings, and number 
registers. 

4.1 Displays 

Occasionally you want to make sure that a certain stretch of text is kept 
all together on one page. For instance, it is generally preferred that the 
information in a table not be split across page breaks, tbl does not 
provide this service, but mm provides a way of doing it, with displays. 
A display is a block of text that is to be kept on one page. 

You can indicate a display by enclosing the relevant text within the pair 
of macros .DSand . de, as follows: 
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.DS 

This text will be kept all together. 

No heading macros are allowed in a display, 

but paragraph macros and lists are allowed. 

By default the text of a display is not 

filled or adjusted, but you can override 

this by providing an argument 

to the .DS macro. 

.DE 

If there is not enough space remaining on the page to fit this entire 
block, t rof f will break onto a new page, so that the block remains 
together. 

4.2 Lists 

Occasionally you want to provide a list of items. The mm package 
provides a number of macros designed to facilitate printing lists of 
various kinds. For instance, 

• P 

The remaining suspects are: 

• sp .5 
.BL 
.LI 
Tim 
.LI 
Joe 
.LI 

the butler 

.LI 

the maid 

.LE 

• sp 

produces 
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The remaining suspects are: 

• Tim 

• Joe 

• the butler 

• the maid 

The macro . bl is a list initialization macro; it instructs mm that a bullet 
list follows. The macro . Li indicates the beginning of each list item, 
and the macro . LE indicates the end of the list. 

There are a number of other list initialization macros: 



.AL 


numbered or lettered list 


.BL 


bullet list 


.DL 


dashed list 


.ML 


marked list 


• RL 


reference list 


• VL 


variable-item list 



As you would expect, the format of the list can be adjusted as needed; 
see Chapter 4, "mm Reference," for details. 

4.3 Table Of contents 

mm is able to generate a table of contents for your document by 
remembering all section headings and the pages where they occur as it 
formats the document. To get the table of contents printed, you must 
include the following macro at the end of your input file: 

.TC 

This macro causes mm to print out the accumulated section headings 
and page numbers. You may control the appearance of the table by 
adding arguments to the macro (see Chapter 4, "mm Reference"). 

4.4 Multicolumn output 

By default, trof f outputs the text in one column. You can instruct it 
to print two columns with the macro 

.2C 
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To return to one column, use the macro 

• IC 

4.5 Strings 

A string is a sequence of characters grouped together under a name. 
The inm macro package provides several predefined strings that you can 
use. For instance, the string \ * (dt will be replaced by the current 
date, as follows: 

Today is \* (DT. 

This results in 

Today is September 16, 1987. 

You get access to a string by preceding its name with the sequence 
\ * ( (or, as we saw above, with the sequence \ * if the name of the 
string is only one character). In addition, you may define your own 
strings with the t rof f command . ds. This might be useful to 
abbreviate an often-used but lengthy phrase: 

.ds CU Pig Farmers of America Credit Union 

.P 

The annual board meeting of the \*(CU 

was called to order at 2:11 p.m. 

Chairman Curley reported 

an unexpected rise 

This produces 

The annual board meeting of the Pig Farmers of 
America Credit Union was called to order at 2: 1 1 p.m. 
Chairman Curley reported an unexpected rise 

4.6 Number registers 

t rof f keeps track of many of the parameters governing the page 
layout by storing them in number registers. You may think of a 
number register as a slot having both a label (the name of the register) 
and something inside it (the value of the number register). Some of 
these registers are created and manipulated by t rof f and mm 
themselves, but you may also define your own number registers. 
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You can create a number register with the command . nr: 

.nr YR 8 6 

The profit in year 19\n(YR was $250,000. 

In the text, you must precede the number register (here, yr) with \n. 
The value you defined in the number register then appears in the 
output: 

The profit in year 1986 was $250,000. 

A more typical use of the . nr command is to change built-in 
parameters. For instance, you can use the command 

.nr Pi 10 

to change the paragraph indent to 10 ens. See Chapter 4, "mm 
Reference," for a complete list of number registers. 

4.7 Defining and using macros 

If you find yourself repeating the same sequence of t rof f commands, 
or almost the same sequence, you may find it useful to define a macro 
encapsulating that sequence of commands. You define a macro with 
the . de macro. For instance, 

.de QP 
. in +5n 
.11 -lOn 
• ps -2 



The line consisting of two dots indicates the end of the macro. Here 
we have defined a rudimentary quote paragraph macro: it indents the 
text from both sides and reduces the point size by 2. 

You can also define macros with "arguments," like many of the mm 
macros. The arguments are indicated in the definition with the 
sequences \\$1,\\$2, and so on. For example, 

.de XX 

Today is \\$1 the \\$2. 

.XX Friday 6th 
yields 
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Today is Friday the 6th. 

Macro names should be chosen carefully to avoid conflicts with 
predefined mm macro names. To be safe, user-defined macros should 
be two characters with the first lowercase and the second uppercase. 
For example, 

.de mN 

4.8 Motions 

trof f includes commands for making arbitrary motions in a 
horizontal or vertical direction, \h and \v. For example. 

There is a gap \h'0.5i' in this sentence. 

yields 

There is a gap in this sentence. 

Both \h and \v require a distance specification within single quotes; 
the two escape sequences \u and \d, however, move up and down a 
fixed distance and so require no argument. For example, 

This sentence contains a superscript\ul\d. 

yields 

rr^ . • 1 

This sentence contams a superscnpt . 

4.9 Line drawing 

There are two trof f commands for drawing horizontal and vertical 
lines, \1 and \L. For example, 

\l'0.5i'\L'0.5i' 

prints 



5. Document printing 

trof f produces output that is device independent. This means that 
you will need to process the output of trof f with a program (usually 
called an "interface program") that translates this output into a form 
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that the printer understands. This step of the printing process may be 
done automatically, or you may need to invoke this program yourself. 
Check with local administrators to see what is appropriate for your 
installation. On the AAJX system, an interface program is provided to 
allow t rof f output to be printed on the LaserWriter; it is called 
psdit and is discussed below in "The TranScript Package." 

5.1 Output devices 

The AAJX family of text processing tools is designed to be as 
independent of any particular type of output device as possible, thereby 
allowing the user to get output on any of a wide number of printers or 
display devices. On the high end of the spectrum, t rof f is capable of 
producing output on modem digital typesetters and phototypesetters, 
and on laser-driven printers, whose quality approaches that of much 
more expensive typesetters, t rof f can also send output to certain 
high-resolution video display terminals. On the low end of the 
spectrum, nrof f can format its input for output on virtually any 
terminal screen, dot matrix printer, or daisy wheel printer, 

5.2 The Transcript pacl<age 

As indicated above, a printer interface program is needed to translate 
the output of t rof f into a form that is understood by your printer. If 
you wish to produce output on an Apple LaserWriter, you must pipe 
the output of t rof f through a program that translates it into 
PostScript, the page-description language used by the LaserWriter. For 
this purpose, the AAJX system contains a package of programs called 
TranScript. 

The most important program in this package is psdit, which 
translates t rof f output into PostScript. For instance, the command 
line used in producing this chapter was 

grap chap.l | pic I tbl | eqn | troff -Tpsc -mm | psdit | Ip 

The only thing new here, aside from the postprocessor psdit, is the 
-Tpsc option to troff. This tells troff which type of printer it 
should format its output for; troff needs this information so that it 
can know which point sizes are legal for that printer and which fonts 
are available on the printer (among other things). The psc stands for 
"PostScript device" and is the appropriate option for the LaserWriter. 
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For more information on the TranScript package, consult 
transcript(lM) in AlUX System Administrator' s Reference. 
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Introduction 

troff is the A/UX text processing program that formats text for 
typeset-quality output on a typesetter or laser printer, iran (for 
"Memorandum Macros") is a general-purpose package of text 
formatting macros for use with troff. The examples in this tutorial 
were produced on the Apple® LaserWriter printer. This chapter 
assumes that you have already been through the vi tutorial in Getting 
Started With A/UX. 

This chapter takes you through some of the basics of troff in three 
tutorial lessons. The first lesson concentrates on producing a business 
letter. The second lesson shows you how to create a simple design for 
letterhead stationery. The third and final lesson takes you through some 
modifications of the letter's appearance. 

While these three lessons don't by any means teach you all that troff 
has to offer, they should get you well on your way to using troff 
(with the mm macros) to produce typeset-quality output. 

Lesson 1 : Producing a formatted letter 

To create a business letter using troff and mm, you must first create a 
new file by invoking one of the AAJX text editors, such as vi. Type 

vi letter 

and press Return. 

Once you have opened the new file, you can use vi commands to enter 
text and troff and mm commands. The troff and mm commands 
you enter affect how the text will appear on the printed page. 

You can enter t rof f and mm commands just as you enter text, but 
they are preceded by a period at the beginning of a line, or by a 
backslash (\). For example, the troff command 
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.sp 

tells the printer to leave one blank line on the printed page. The 
command 

\fCtroff\fR 

causes the word "troff ' to print out in Courier font, but words after 
"troff" will return to roman font. 

Using mm displays 

By default, troff "adjusts" text to fill a line up to the right margin. If 
you want to print a small section of short lines, for example the name 
and address of the person to whom you are writing, enter the text in a 
display; this tells troff to print the text just as you have entered it. 
Type 

.DS 

Ms. Pandora S. Bach 

Comparative Surveys, Inc. 

7 9 Downing Street 

San Jose, California 95128 

.DE 

The . DS and , DE are rran macros that stand for "display start" and 
"display end." 

When you print the letter, the name and address print out as follows: 

Ms. Pandora S. Bach 
Comparative Surveys, Inc. 
79 Downing Street 
San Jose, California 95128 

Paragraphs and spaces 

You can leave a space and a half on the printed page between the 
address and the salutation by using . p, the paragraph macro. Type 

.P 
on the line below . DE, and follow it with 

Dear Ms . Bach: 
on the next Une, followed with another . P on the line after that. The 
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file now looks like 

.DS 

Ms . Pandora S . Bach 
Comparative Surveys, Inc. 
7 9 Downing Street 
San Jose, California 95128 

.DE 

.P 

Dear Ms . Bach: 

.P 

where . P stands for "paragraph." Use the paragraph macro wherever 
you want to leave extra space or start a paragraph. 

Lists 

The body of this letter lists four items. To print them out in a bullet 
list, with each item preceded by a bullet and indented five spaces, use 
the bullet Hst macro. Starting at the line below the second . P, type 

.P 

Enclosed please find the following items : 

.BL 5 

.LI 

A copy of a message from Ms. Gail Smith 

dated March 6 . 

.LI 

A copy of the worksheet you requested. 

.LI 

A \f (BIComparative Surveys\fR records 

form and relevant information. 

.LE 

.P 

Thank you for your attention to this account. 

.P 

Printing the file produces the following output: 
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Enclosed please find the following items: 

• A copy of a message from Ms. Gail Smith dated March 6. 

• A copy of the worksheet you requested. 

• A Comparative Surveys records form and relevant 
information. 

Thank you for your attention to this account. 

Font changes 

Note that in the text above, the phrase "Comparative Surveys" prints 
out in bold italic and the words after in roman. This is caused by the 
trof f commands \f (Bl and \fR. 

The first command 

\f (BI 

instructs the printer to print the following text in bold italic Times 
Roman font. 

The second command 

\fR 

instructs the printer to print the following text in Times Roman font. 

Indented text 

To finish off your letter, you can use the indent command ( . in) to 
print text indented on the page. Type 

.in +2i 

Sincerely yours, 

• sp 3 

John C. Doe 

.in -2i 

.sp 

Enclosures 

When you print the file, this prints out as follows: 
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Sincerely yours, 

John C. Doe 
Enclosures 



Formatting your file 

When you have entered all the above text and commands in your file 
letter, save the file on disk and exit vi. When you see the shell 
prompt on your screen again, you are ready to format your file and send 
it to the printer. (See A/UX Local System Administration for 
information about setting up a printer.) 

At the shell prompt, type 

troff -Tpsc -mm letter | psdit | Ip 

This command line sends your file through the troff program and mm 
macros, then sends it to a postprocessor, psdit, that prepares it for the 
LaserWriter, and finally sends it to the printer. See Chapter 1, 
"Introduction to A/UX Text Processing," and the reference chapters 
that follow for more information. 

Obtaining your printout 

When the printer has received your file, you will see a message on your 
screen. Figures 2-1 and 2-2 show your file letter as it appears on 
your screen and on the printed page that is produced. 
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Figure 2-1 . Contents of your file with text and trof f /mm code 

.DS 

Ms . Pandora S . Bach 
Comparative Surveys, Inc. 
7 9 Downing Street 
San JosG;. California 95128 
.DE 
.P 

Dear Ms. Bach: 
.P 
.P 

Enclosed please find the following items : 
.BL 5 
.LI 

A copy of a message from Ms. Gail Smith 
dated March 6 . 
.LI 

A copy of the worksheet you requested. 
.LI 

A \f (BIComparative Surveys\fR 
records form and relevant information. 
.LE 
.P 

Thank you for your attention to this account . 
.P 

.in +2i 

Sincerely yours, 
. sp 3 

John C . Doe 
.in -2i 
.sp 
Enclosures 
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Figure 2-2. File printed on a LaserWriter 

Ms. Pandora S. Bach 
Comparative Surveys, Inc. 
79 Downing Street 
San Jose, California 95128 

Dear Ms. Bach: 

Enclosed please find the following items: 

• A copy of a message from Ms. Gail Smith dated March 6. 

• A copy of the worksheet you requested. 

• A Comparative Surveys records form and relevant information. 
Thank you for your attention to this account. 

Sincerely yours. 



John C. Doe 
Enclosures 



Lesson 2: Producing letterhead 

To create letterhead stationery, you may first create a new file by 
invoking one of the AAJX text editors such as vi. Create the new file, 
letterhead, by typing 

vi letterhead 

Once you have opened the new file, you can use vi commands to enter 
text and trof f and mm commands to format it. 

This simple letterhead will consist of John Doe's name and address at 
the top of a page. Because of the physical size of this manual, the 
stationery will print out smaller than standard 8.5-by-ll-inch paper. In 
' 'The Size of your Page' ' you will see how to change the code to print 
out a larger version of this letterhead. 
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Top-of-page processing 

The trof f program uses several internal defaults to define how text 
will print out. You can change these defaults to fine-tune the format of 
your printed page. 

For example, t rof f prints a page number at the top of each page. To 
prevent this, you can change the "page header" macro's definition. 
The page header macro accepts three fields: the left side of the page, 
the center, and the right side. In the definition, the three fields are 
separated by single quotes. 

At the top of the file, type 

pu u r r r r u 

This defines all three fields as empty. 

You may define how many spaces are left at the top of the page, using 
the definition 

.de TP 
.sp 2 

This tells the printer to start printing text two spaces below the default 
of 1 inch. Enter this definition in the file, below the page header macro. 

The size of your text 

The t rof f program uses point size 10 by default. This is the point 
size used in this manual. If you want the text of your letter (and any 
text in your letterhead) to appear in point size 10, you don't need to 
specify this to trof f. However, if you want the text to appear slightly 
larger, for example, point size 11, you can use the mm command 

.S 11 13 

This changes the default point size to 11 and the vertical spacing to 

13. 

The size of your page 

Because of the physical size of this manual, the stationery will print out 
smaller than standard 8.5-by-ll-inch paper. The length of a line of 
text, the width of the margin, and the length of the page itself are 
defined using number registers. Number registers are assigned values 
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as follows: 

.nr w 4i specifies a 4-inch line 

.nr 2i specifies 2-inch margins 

.nr L Hi specifies an 11 -inch page 

The w number register stands for the "width" of the text, and the O 
register stands of the "offset" from the physical width of the page. 

To print out a standard-size page, change these definitions as follows: 

.nr w 6i specifies a 6-inch line 

.nr li specifies 1 -inch margins 

.nr L Hi specifies an 11 -inch page 

Designing your ietterliead 

Enter the following commands in your file: 

.sp 

\lMi' 

.sp 

\sl4John C. Doe\sO 

• br 

\lMi' 

. sp -1.75m 

\lMi^ 

.sp .25 

.tl '"XsgX&P.O. Box 14, Carter, CA 94530\sO' 

.sp 

.tl "'\*(DT' 

.sp 2 

These commands are listed below with comment lines that describe 
what each one tells the printer to do. 
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.sp 


Leave one blank line. 


\l'4i'' 


Draw a line 4 inches long. 


.sp 


Leave one blank line. 


\sl4John C. Doe\sO 


Print this text in point size 14. 


.br 


Break line here (go to next line), 


\lMi' 


Draw a line 4 inches long. 


. sp -1.75m 


Go back up 1.75 "m" units. 


\lMi' 


Draw a line 4 inches long. 


.sp .25 


Leave 1/4 vertical space. 


.tl ' ' '\s9\&P.O. Box 


14, Carter, CA 94530\s0' 




Print this text in point size 




9, on the right side of the line. 


.sp 


Leave one blank line. 


.tl "''\*(DT' 


Print the current date on the 




right side of the line. 


.sp 2 


Leave two blank lines. 



Note that the string \ * (dt will print the current date (the date on 
which you format your letter). The "title" request 

.tl ' " ' 

is similar to the page header macro described above in that it defines 
three separate fields, enclosed in single quotes. The three fields are the 
left side of the page, the center, and the right side. In the letterhead 
definition above, the title request is used to justify a string of text on the 
right side of the page. 

If you format your letterhead file using the trof f command line 
shown under ' 'Obtaining your Printout," your letterhead looks like the 
output in Figure 2-3. 
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Figure 2-3. A sample letterhead 



John C. Doe 



P.O. Box 14, Carter, CA 94530 
August 28, 1987 



Printing your letter on letterhead 

Now that you have created a file containing the trof f and mm codes 
to produce letterhead stationery, save the file on disk and exit vi. You 
can now use this letterhead with any letters you write by formatting it 
on the same command line as your letter. Because the letterhead must 
print before the text of your letter, the command line should look hke 
this: 

troff -Tpsc -mm letterhead letter | psdit | Ip 

This command line sends both files through the trof f program and 
mm macros. The letter this produces looks hke the one in Figure 2-4. 
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Figure 2-4. Sample letter 



John C. Doe 



P.O. Box 14, Carter, CA 94530 
August 28, 1987 

Ms. Pandora S. Bach 
Comparative Surveys, Inc. 
79 Downing Street 
San Jose, California 95128 

Dear Ms. Bach: 

Enclosed please find the following items: 

• A copy of a message from Ms. Gail Smith dated March 6. 

• A copy of the worksheet you requested. 

• A Comparative Surveys records form and relevant information. 
Thank you for your attention to this account. 

Sincerely yours, 



John C. Doe 



Enclosures 
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Lesson 3: Modifying the appearance of a page 

Now that you have created a simple letter and printed it out on 
letterhead stationery, you may want to modify the letter to include 
more information. In this lesson, you will learn how to produce a 
footnote and line graphics in your letter. 

Producing a footnote 

To include a footnote in your file named letter, first open the file 
using an editor such as vi: 

vi letter 

Move your cursor to the place in the file where you want the footnote 
to be referenced. This example uses a ' 'dagger" symbol rather than a 
number. For example, move to the line in your file that reads 

A copy of the worksheet you requested. 

and place the dagger symbol at the end of the line: 

A copy of the worksheet you requested. \ (dg 

When you include a footnote in your text, use the mm footnote macros. 
. FS stands for "foomote start" and . FE for "footnote end." These 
should be placed as close as possible to the footnote reference (in this 
case, \ ( dg). On the next line in your file, type 

.FS \(dg 

Note that the worksheet is dated March 20. 

.FE 

Your letter will look like the one in Figure 2-5. 
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Figure 2-5. A sample letter with a footnote 



John C. Doe 



P.O. Box 14, Carter, CA 94530 
August 28, 1987 

Ms. Pandora S. Bach 
Comparative Surveys, Inc. 
79 Downing Street 
San Jose, California 95128 

Dear Ms. Bach: 

Enclosed please find the following items: 

• A copy of a message from Ms. Gail Smith dated March 6. 

• A copy of the worksheet you requested, t 

• A Comparative Surveys records form and relevant information. 
Thank you for your attention to this account. 

Sincerely yours, 



John C. Doe 



Enclosures 



t Please note that the worksheet is dated March 20. 
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Producing graphics 

You can include simple line drawings in a document by using the 
preprocessor pic after you've entered appropriate picture 
specifications in your file. 

Graphics can be useful in documents. For example, you might want to 
order some printed envelopes to go along with your custom stationery. 
A good way to let the printer know how you want it to look is to 
enclose a picture of the printed envelope (a picture is worth . . .). You 
can specify such a picture by including the following input in your file: 

.PS 

A: box ht 2i wid 4i 

line from A.nw to A.c 

line from A.ne to A.c 

box invis ht .751 "John C. Doe" "P.O. Box 14"\ 

"Carter, CA" "94350" with .n at A.n 

.PE 

You can then process this with the command line 

pic letter | troff -Tpsc -mm | psdit | Ip 
The output, in part, will look like Figure 2-6. 

Figure 2-6. Sample line graphic 
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1. Introduction 

This document is not geared toward the beginner but toward someone 
who is already famihar with using macro packages and is interested in 
altering or writing macros. It is also a useful reference for nrof f and 
trof f commands that are not available in existing macro packages. 

The nrof f text formatter formats text for typewriter-like terminals. 

The trof f formatter formats text destined to be printed on a 
phototypesetter, but is intended to be converted by a postprocessor into 
codes that will drive a particular phototypesetter. 

Both nrof f and trof f processors accept Unes of text interspersed 
with lines of format control information. They format the text into a 
printable, paginated document having a user-designed style. The 
nrof f and trof f formatters offer unusual freedom in document 
styling, including 

• Versatile paragraph and section control 

• Flexible-style headers and footers 

• Generation of footnotes 

• Automatic sequence numbering for paragraphs and sections 

• Multiple column output 

• Font and point-size control (trof f only) 

• Arbitrary horizontal and vertical local motions at any point 

• Overstriking, bracket construction, and line drawing functions. 

Because nrof f and trof f formatters are reasonably compatible, it is 
usually possible to prepare input acceptable to both. Conditional input 
is provided that enables you to embed input expressly destined for 
either program (see "Conditional acceptance of input"). For example, 

.if n . sp \"if nroff/ then go one space 

.if t . sp .5 \"if troff, then go one-half space 
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The major dissimilarity between the two formatters is spacing, nrof f 
does not have fractional-space capabilities. A trof f vertical-space 
request, such as . sp .5, will be ignored or . sp 1.3 will be treated 
as one space by nrof f . Keep in mind that nrof f output devices use 
constant-width characters, whereas in trof f , character widths vary. 
This is important when determining distances for setting tabs. Local- 
motion escape characters also have different effects in nrof f and 
trof f (see "Local Motion"). 

The nrof f formatter can prepare output directly for a variety of 
terminal types and is capable of utiUzing the full resolution of each 
terminal. 

The trof f text formatter is a program that can drive virtually any 
phototypesetter, because its output is an ASCII code describing the 
position, font, size, and so on, of characters to be typeset on a page. 
This output must be converted by another program, called a 
postprocessor, into codes a particular phototypesetter will understand. 
Parameters such as fonts, character sizes, and special characters depend 
on the phototypesetter being driven. 

Full user control over fonts, sizes, and character positions, as well as 
the usual features of a formatter (right-margin justification, automatic 
hyphenation, page titling and numbering, and so on) are provided by 
the trof f processor. It also provides macros, arithmetic variables and 
operations, and conditional testing for complicated formatting tasks. 

2. Usage 

The general form of invoking an nrof f or trof f formatter at the 
AAJX operating system command level is 

nrof f [options] \files] 
or 

trof f [options] [files] 

where options represents any of a number of flag options and files 
represents the list of files containing the document to be formatted. An 
argument consisting of a single minus sign (-) is taken to be a filename 
corresponding to the standard input. Input is taken from the standard 
input if no filenames are given. Options may appear in any order but 
must appear before the files. 
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Option Effect 

- a (t r o f f only.) Send a printable approximation in 

American Standard Code for Information Interchange 
(ASCII) character set of the results to the standard output. 
This approximates a display of the document. 

-e (nrof f only.) Produce equally spaced words in adjusted 

lines using full terminal resolution. 

-Fdir Get access to font information from the directory 

dir / devname where name is the default output device. 
The default font information directory is 

/usr/lib/font/devname. 

-h (nrof f only.) Use output tabs during horizontal spacing 

to speed output and to reduce output byte count. Device 
tab settings are assumed to be every eight nominal 
character widths. The default settings of logical input tabs 
are also every eight nominal character widths. 

-i Read standard input after the input files are exhausted. 

-mname Prefix the /usr/lib/tmac/tmac.name macro file to 
the input files. Multiple -m macro package requests on a 
command line are accepted and are processed in sequence. 

-nn Number the first generated page n. 

-oHst Print only pages whose page numbers appear in list, which 

can consist of comma-separated numbers, number ranges, 
or both. 

• A list of comma-separated numbers such as n, m 
means pages n and m. 

• A number range has the form n-m and means pages 
n through m. 

• An initial -n means from the beginning to page n. 

• A final n- means from page n to the end. 

-q Invoke the simultaneous input/output mode of the .rd 

request. 
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- rxn Set register x (one character) to n. 

-sn Stop every rt pages. Thenroff formatter will halt after 

every n pages (default «=1) to allow paper loading or 
changing and will resume upon receipt of a new line. 
When using t rof f , it is probably preferable to use the -s 
option on the postprocessor if one exists. 

-Uname Specify the name of the output terminal type. Currently 
defined names are: Ip for generic printers that can 
underline and tab, 2 6 3 1 for the Hewlett-Packard 263 1 
printer in regular mode, 2 63 1-c for the Hewlett-Packard 
2631 printer in compressed mode, 2 63 1-e for the 
Hewlett Packard 2631 printer in expanded mode, 3 for 
the DASI 300, 30 0-12 for DASI 300 terminal set to 12- 
pitch, 3 s for the DASI 300s, 3 s - 1 2 for DASI 300s 
terminal set to 12-pitch, 37 for the TELETYPE Model 37 
(nrof f default), 382 for the DCT-382 terminal, 4000a 
for the TREND ATA 400a terminal, 450 for the DASI 
450, 450-12 for the DASI 450 set to 12-pitch, 832 for 
the Anderson Jacobson 832 terminal, 8 5 1 for the 
C.rrOH printer, t n3 for the GE TermiNet 300 (or any 
terminal without half-line capabilities), X for the EBCDIC 
TX train printer. 

In trof f , the -T option may be used to specify the output 
device. The psc argument ("trof f -Tpsc") is 
required for PostScript output on a LaserWriter. (This is 
the AAJX trof f default.) 

-u[/i] (nrof f only.) Set the emboldening factor (number of 

character overstrikes) in the formatter for the third font 
position (bold) to be n (zero if n is missing). It is not 
possible to turn off the emboldening in nrof f if the 
overstriking is controlled locally by the printing device. 

- z Suppress formatted output. Only message output will 

occur (from . tm requests and diagnostics). 

Each option is invoked as a separate argument. For example, 



3-4 A/UX Text Processing Tools 



nroff -o4,8-10 -T300s -mabc chapterl chapter2 

requests formatting of pages 4, 8, 9, and 10 of a document contained in 
the files named chapterl and chapter2, specifies the output 
terminal as a DASI 300s, and invokes the macro package abc. 

Various preprocessors and postprocessors are available for use with the 
nroff and trof f formatters: 

• The equation preprocessors are neqn and eqn (for nroff and 
trof f formatters, respectively). 

• The table-construction preprocessor is tbl. 

• The picture drawing preprocessor for the trof f formatter is 

pic. 

• A reverse-line postprocessor for multiple-column nroff 
formatter output on terminals without reverse-line ability is col. 
The TELETYPE Model 37 escape sequences that the nroff 
formatter produces by default are expected by col. 

trof f output can be viewed on the Teletype Model 5620. No special 
filter is required to postprocess t rof f 's output for the 5620. The 
finished version of a document typeset with trof f is most jfrequently 
sent to a phototypesetter 

tbl file I eqn | trof f {options] \ typesetter 

The first pipe ( I ) indicates the piping of tbl output to eqn input; the 
second pipe indicates the piping of eqn output to the t rof f formatter 
input. Finally, the accumulated output from these processes is piped to 
a postprocessor that interprets trof f 's output language for the output 
device. 

tc is a phototypesetter-simulator postprocessor, which enables you to 
view trof f output on a Tektronix 4014 terminal. The syntax for its 
usage is as follows: 

pic file I tbl I eqn | trof f [options] I tc 

The t rof f formatter depends on a postprocessor to convert its output 
into codes for a particular phototypesetter. 
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3. General information 

This section describes some general principles of the nrof f and 
trof f formatters. 

3.1 Form of Input 

Input data consists of text lines, which are destined to be printed, 
interspersed with control lines, which set parameters or otherwise 
control subsequent processing. Control lines begin with a control 
character, normally a period or an acute accent (' ), followed by a 1- or 
2-character name that specifies a basic request or the substitution of a 
user-defined macro in place of the control line. The acute accent 
control character suppresses the break function (the forced output of a 
partially filled line) caused by certain requests. Control characters may 
be separated from request/macro names by white space (spaces, tabs or 
both) for aesthetic reasons. Names must be followed by either a space 
or a newUne character. Control lines with unrecognized request/macro 
names are ignored. There are tables in each section of this chapter that 
contain explanations of the request/macro names. 

Various special functions may be introduced anywhere in the input by 
means of an escape character (\). For example, the function \nr 
causes the interpolation of the contents of the number register r in place 
of the function. Number register r is either x for a single letter register 
name or (xc for a 2-character register name. These escape sequences 
for characters, indicators, and functions are summarized at the end of 
this chapter. 

3.2 Formatter and device resolution 

The nrof f processor internally uses 240 units/inch, corresponding to 
the least common multiple of the horizontal and vertical resolutions of 
various typewriter-like output devices. Units in trof f are device- 
dependent, trof f rounds horizontal/vertical numeric parameter input 
to its internal horizontal/vertical resolution, nrof f similarly rounds 
numeric input to the actual resolution of the output device indicated by 
the -T option (default TELETYPE Model 37). 

3.3 Numeric parameter input 

Both nrof f and trof f formatters accept numeric input with the 
appended scale indicators shown in the following table, where S is the 
current type size in points, V is the current vertical line spacing in basic 
units, and C is a nominal character width in basic units. The number of 



3-6 A/UX Text Processing Tools 



basic units is device-dependent in trof f . 



Scale 
indicator 


Meaning 


Number of basic units 


nroff 


i 


Inch 


240 


c 


Centimeter 


240x50/127 


P 


Pica = 1/6 inch 


240/6 


m 


em = 5 points 


C 


n 


en = em/2 


C, same as em 


P 


Point =1/72 inch 


240/72 


u 


Basic unit 


1 


V 


Vertical line space 


V 


none 


Default 





In nroff processors, both em and en are taken to be equal to C, which 
is output-device dependent; common values are 1/10 and 1/12 inch. 
Actual character widths in the nroff formatter need not be all the 
same. Constructed characters (such as ->) are often extra wide. 
Default scaling is: 

• em for horizontally oriented requests ( . 11, . in, . t i, . ta, 
. It, .po, .mc) and functions (\h, \1). 

• yforvertically oriented requests (.pi, .wh, .ch, .dt, .sp, 
. sv, . ne, . rt) and functions (\v, \x, \L) 

• p for requests . vs, . vs and functions \H and \s. 

• u for . nr, .if, and . ie requests. 

All other requests ignore scale indicators. When a number register 
containing an already appropriately scaled number is interpolated to 
provide numeric input, the basic unit scale indicator (u) may need to be 
appended to prevent an additional inappropriate default scaling. The 
number, n, may be specified in decimal-fraction form but the parameter 
finally stored is rounded to an integer number of basic units. 

The absolute position indicator ( | ) may be prefixed to a number n to 
generate the distance to the vertical or horizontal place n. 

• For vertically oriented requests and functions, I n becomes the 
distance in basic units from the current vertical place on the page 
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or in a diversion (see "Macros, Strings, Diversions, and Position 
Traps") to the vertical place n. 

m For all other requests and functions, I n becomes the distance 
from the current horizontal place on the input line to the 
horizontal place n. 

For example, 

.sp I 3.2c 

will space in the required direction to 3.2 centimeters from the top of 
the page. 

3.4 Numeric expressions 

Wherever numeric input is expected, the following may be used: 

• an expression involving parentheses 

• the arithmetic operators +,-,/,*,% (mod) 

• the logical operators <, >, <=, >=, =, ==, & (and), : (or) 

Except where controlled by parentheses, evaluation of expressions is 
left to right; there is no operator precedence. In the case of certain 
requests, an initial + or - is stripped and interpreted as an increment or 
decrement indicator. In the presence of default scaling, the desired 
scale indicator must be attached to every number in an expression for 
which the desired and default scaling differ. For example, if the 
number register x contains 2 and the current point size is 10, then 

.11 (4.25i+\nxP+3m) /2u 

sets the line length to Vi the sum of 4.25 inches + 2 picas + 3 ems (30 
points because the point size is 10). 

Note: The use of white space in arithmetic expressions is not 
permitted. There is no precedence among arithmetic and 
logical operators, nrof f/trof f expressions do not recognize 
decimal multipliers or divisors; a high level of precision may be 
achieved by mixing scales within expressions. 
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3.5 Notation 

Numeric parameters are indicated in this chapter in two ways. A ±n 
means that the argument may take the forms n, +n, or -n and that the 
corresponding effect is to set the affected parameter to n, to increment 
it by n, or to decrement it by n, respectively. Plain n means that an 
initial algebraic sign is not an increment indicator but merely the sign 
of n. Generally, numeric input is either ignored or truncated to a 
reasonable value. For example, most requests expect to set parameters 
to non-negative values; exceptions are . sp, . wh, . ch, . nr, and . if. 
If no argument is specified, then the . ps, . ft, . po, . vs, . Is, . 11, 
. in, and . It requests restore the previous value. 

Single character arguments are indicated by single lowercase letters 
and one- or two-character arguments are indicated by a pair of 
lowercase letters. Character string arguments are indicated by 
multicharacter mnemonics. 

4. Font and character size control 
4.1 Cliaracter Set 

The trof f character set consists of the so-called Commercial II 
character set plus a Special Mathematical font character set. The 
ASCII characters are entered as themselves (with three exceptions); 
and non- ASCII characters are entered in the form \ (re, where xx is a 
two-character name given at the end of this chapter. The three ASCII 
character exceptions are mapped as follows: 



ASCII input 


Printed by trof f 


Character 


Name 


Character 


Name 


^ 


Acute accent 
Grave accent 
Minus 


) 
( 


Close quote 
Open quote 
Hyphen 



The characters ', " , and - may be entered by typing \ ' , W and \ -, 
respectively, or by typing their names (\ (aa, \ (ga, and \ (mi). The 
ASCII characters (§),#,",', \ <, >,\ {,}, ~, ", and _ exist on the 
Special Mathematical font and are printed as a one-em space if that 
font is not mounted. 
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The nrof f processor understands the entire trof f character set but 
can print only: 

• ASCII characters 

• Additional characters that are available on the output device 

• Characters that can be constructed by overstriking or by other 
combinations 

• Characters that can be mapped into other printable characters. 

Each printer's capability is determined by a driving table prepared for 
each device. The characters ', \ and - print as themselves. 

4.2 Fonts 

Default fonts may differ from device to device. Typically, the fonts 
will include at least the following: Times Roman (r), Times Italic (l), 
Times Bold (B), and Special Mathematical (S). The current font may 
be changed by use of the . ft request or by embedding at any desired 
point either \ f x, \ f (xx, or \ f n where x and xx are the name of a 
mounted font and n is a numeric font position. It is not necessary to 
change to the Special Font; characters on that font are automatically 
handled. They are invoked by their four-character input names (see 
"Character Set"). 

A request for a named but not mounted font is translated into a request 
to mount the font at position zero. This position is reserved for such 
dynamic requests and is otherwise inaccessible. The trof f processor 
can be informed that any particular font is mounted by use of the . f p 
request. The list of known fonts is device-dependent. In the 
subsequent discussion of font-related requests, /represents either a one- 
or two-character font name or the numeric font position. The current 
font is available as numeric position in the read-only number register 
• f. 

Font control is understood by the nrof f formatter which normally 
underlines italic characters and overstrikes bold characters. Other font 
changes are usually ignored. 

4.3 Character Size 

The available character point sizes depend on the individual printing 
device. The . ps request is used to change or to restore the default 
point size. Alternatively, the point size may be changed between any 
two characters by embedding a \ sn at the desired point to set the size 
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to n or a \ s±rt (1 < n < 9) to increase or decrease the size by n; \ s 
restores the previous size. Requested point size values that are between 
two valid sizes yield the closer legal size. The current size is available 
in the . s number register. 

In trof f the escape sequence \H' n' sets the height of a character 
without affecting its width, n can be expressed in absolute values or in 
relative values of the form ±n. 

Note that the nrof f formatter ignores type size control. 

Request Initial If no _ , 

, ^ , ^ Explanation 

form value argument ^ 

■ cs/[/i][m] off - Set constant character space (width) 

mode on for font/ (if mounted). The 
width of every character is assumed to 
be n/36 ems. If m is absent, the em is 
that of the character point size; if m is 
given, the em is m-points. All affected 
characters are centered in this space 
including those with an actual width 
larger than this space. Special font 
characters occurring while the current 
font is /are also so treated. If n is 
absent, the mode is turned off. The 
mode must still (or again) be in effect 
when the characters are printed. There 
is no effect in the nrof f formatter. 

.ps [±n] 10 point previous Set point size to ±«. Any valid positive 

size value may be requested; if invalid, 
the nearest valid size will result, with a 
maximum size to be determined by the 
individual printing device. A paired 
sequence +n, -n wiU work because the 
previous requested value is 
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Request initial If no _ , 

form value argument Explanat.on 

remembered. For point size changes 
within a line of text, sequences \sn or 
\s+ncanbeused. Relevant 
parameters are a part of the current 
environment. There is no effect in the 
nrof f formatter. 

■ss n 12/36 em ignored Set space-character size to n/3 6 ems. 

This size is the minimum word spacing 
in adjusted text. Relevant parameters 
are a part of the current environment. 
There is no effect in the nrof f 
formatter. 

.bd / [n] off - Embolden font/by n-1 units. 

Characters in font/ will be artificially 
emboldened by printing each one twice, 
separated by n-1 basic units. A 
reasonable value forn is 3 when the 
character size is in the vicinity of 10 
points. If n is missing, the embolden 
mode is turned off. The mode must 
still (or again) be in effect when the 
characters are physically printed. 

.bd s/n off - Embolden special font when current 

font is/. The characters in the special 
font will be emboldened whenever the 
current font is/. The mode must still 
(or again) be in effect when the 
characters are physically printed. 

.fp nf\file] R,i,B,s ignored Position font. A font named/is 

mounted on position n. It is a fatal 
error if /is not known. . f p accepts a 
third optional argument, //e, which is 
an alternate version of the font/. 
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Request Initial If no _ . .. 

form vaiue argument "^ 

.ft lf\ roman previous Change to font/ (/"is x,x3C, n, or P). 

Font P means the previous font. For 
font changes within a line of text, 
sequences \fx, \f (xx, or \f n can be 
used. Relevant parameters are a part of 
the current environment. 



. bd can be used to embolden characters, effectively increasing the 
number of available fonts. This capability of modifying existing fonts 
to make new ones is enhanced with the trof f escape sequence, \S, 
used to slant output characters by a number of specified degrees. This 
escape sequence is stated as \S ' n' where n may be any integer, 
negative or positive. turns slanting off. 

5. Page control 

Top and bottom margins are not automatically provided. They may be 
defined by two macros which set traps at vertical positions (top) and 
-n (n from the bottom) (see "Traps"). A pseudo-page transition onto 
the first page occurs either when the first break occurs or when the first 
nondiverted text processing occurs. Arrangements for a trap to occur 
at the top of the first page must be completed before this transition. 
References to the current diversion mean that the mechanism being 
described works during both ordinary and diverted output (the former 
is considered as the top diversion level). 

Physical limitations on the nrof f and t rof f processor output are 
output-device dependent. 

Note: Values separated by a semicolon (;) in the "Initial 
value "field below are for the nrof f and trof f formatters, 
respectively. 
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Request Initial If no _ , ., 

form value argument Explanation 



• bp [±n] n = 1 - Begin page. The current page is 

ejected and a new page is begun. If ±n 
is given, the new page number will be 
±n. The scale indicator is ignored if 
not specified in the request. The 
request causes a break. The use of ' as 
the control character (instead of . ) 
suppresses the break function. The 
request with no n is inhibited by the 
.ns request. 

.mk [r] none internal Mark current vertical place in an 

internal register (associated with the 
current diversion level) or in register r, 
if given. The request is used in 
conjunction with "return to marked 
vertical place in current diversion' ' 
request ( . rt). Mode or relevant 
parameters are associated with current 
diversion level. 

• ne [n] - n = Iv Need n vertical spaces. The scale 

indicator is ignored if not specified in 
the request. 

• If the distance to the next trap 
position (d) is less than n, a forward 
vertical space of size d occurs 
which will spring the trap. 

• If there are no remaining traps on 
the page, d is the distance to the 
bottom of the page. 

• If rf is less than vertical spacing (v), 
another line could still be output 
and spring the trap. 

In a diversion, d is the distance to the 
diversion trap (if any) or is very large. 
Mode or relevant parameters are 
associated with current diversion level. 
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Request 
form 



Initial If no 
value argument 



Explanation 



• pl [±n] 



llin 



llin 



.pn ±n 



n=l 



ignored 



.po [±n] 0;lin previous 



.rt [±n] 



internal 



Set page length to ±n. The internal 
limitation is about 75 inches in the 
trof f formatter and 136 inches in the 
nrof f formatter. Current page length 
is available in the . p register. The 
scale indicator is ignored if not 
specified in the request. 

Set page number. The next page (when 
it occurs) will have the page number 
±n. The request must occur before the 
initial pseudopage transition to affect 
the page number of the first page. The 
current page number is in the % 
register. 

Set page offset. The current left margin 
is set to ±n. The scale indicator is 
ignored if not specified in the request. 
The trof f formatter initial value 
provides about 1 inch of paper margin. 
The current page offset is available in 
the . o register. 

Return (upward only) to marked 
vertical place in current diversion. If 
±n (with respect to place) is given, the 
vertical place is ±n from the top of the 
page or diversion. If n is absent, the 
vertical place is marked by a previous 
. mk. The . sp request may be used in 
all cases instead of . rt by spacing to 
the absolute place stored in an explicit 
register; for example, using the 
sequence , mk r . . . . sp | \ \nru. 
Mode or relevant parameters are 
associated with current diversion level. 
The scale indicator is ignored if not 
specified in the request. 
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6. Text filling, adjusting, and centering 

6.1 Filling and adjusting 

Normally, words are collected from input text lines and assembled into 
an output text line until some word does not fit. An attempt may be 
made to hyphenate the word in an effort to assemble a part of it into the 
output line. The spaces between the words on the output line are 
increased to spread out the line to the current line length minus any 
current indent. A word is any string of characters delimited by the 
space character or the beginning or the end of the input line. Any 
adjacent pair of words that must be kept together (neither split across 
output lines nor spread apart in the adjustment process) can be tied 
together using a backslash-space character (\ Space); this separates the 
words with an unpaddable space. The adjusted word spacings are 
uniform in the trof f formatter, and the minimum interword spacing 
can be controlled with the . s s request. In the nrof f formatter, they 
are normally nonuniform because of quantization to character-size 
spaces; however, the flag option -e causes uniform spacing with full 
output device resolution. 

Filling, adjustment, and hyphenation can all be prevented or controlled. 
The text length on the last line output is available in the . n number 
register, and text base-line position on the page for this line is in the nl 
number register. The text base-line high-water mark (lowest place) on 
the current page is in the . h register. 

An input text line ending with period (.), question mark (?), or 
exclamation mark (!) is taken to be the end of a sentence, and an 
additional space character is automatically provided during filling. 
Multiple interword space characters found in the input are retained, 
except for trailing spaces; initial spaces also cause a break. 

To obtain a specific break in a line when filling is in effect, a \p 
sequence may be embedded in or attached to a word to cause a break at 
the end of that word and have the resulting output of the line containing 
that word spread out to fill the current line length. 

A text input line that happens to begin with a control character (such as 
a period) can be made to be interpreted as the actual character itself by 
prefacing it with the nonprinting, zero-width filler character (\ &). 
Another way is to specify output translation of some convenient 
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character into the control character using the . tr request. 

6.1.1 Interrupted text 

Copying an input line in no-fill mode can be interrupted by terminating 
the partial line with a \c escape sequence. The next encountered input 
text line will be considered to be a continuation of the same line of 
input text Similarly, a word within filled text may be interrupted by 
terminating the word, and line, with \ c; the next encountered text will 
be taken as a continuation of the interrupted word. If the intervening 
control lines cause a break, any partial fine or partial word will be 
forced out. 



Request Initial If no _ , 

, ^ , . Explanation 

form value argument ^ 

. ad [n] adjust adjust Adjust. Output lines are adjusted with 

mode n. If the type indicator (n) is 
present, the adjustment type is as 
follows: 



Indicator 


Adjust type 


1 


adjust left margin only 


r 


adjust right margin only 


c 


center 


born 


adjust both margins 


absent 


unchanged 



The adjustment type indicator n may 
also be a number obtained from the . j 
register. If fill mode is not on, 
adjustment will be deferred. Relevant 
parameters are a part of the current 
enviroimient. 

• br - - Break. Filling of the line currently 

being collected is stopped and the line 
is output without adjustment. Text 
lines beginning with space characters 
and empty text lines (blank lines) also 
cause a break. 
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Request Initial If no _ 

form value argument " 



. ce [n] off n = 1 Center. The next n input text lines are 

centered within the current line-length 
(minus indent). If n=0, any residual 
count is cleared. A break occurs after 
each of the n input lines. If the input 
line is too long, it will be left adjusted. 
The request normally causes a break. 
Relevant parameters are a part of the 
current environment. 

. f i fill - Set fiU mode. The request causes a 

break. Subsequent output lines are 
filled to provide an even right margin. 
Relevant parameters are a part of the 
current environment. 

. na adjust - Set no adjust. Output line adjusting is 

not done. Since adjustment is turned 
off, the right margin will be ragged. 
Adjustment typ>e for the . ad request is 
not changed. Output line filling still 
occurs if fill mode is on. Relevant 
parameters are a part of the current 
environment. 

.nf fill - Set no-fill mode. Subsequent output 

lines are neither filled nor adjusted. 
The request normally causes a break. 
Input text Unes are copied directly to 
output lines without regard for the 
current line length. Relevant 
parameters are a part of the current 
aivironment. 

7. Vertical spacing 
7.1 Base-line spacing 

Vertical spacing size (v) between base lines of successive output lines 
can be set using the . vs request with a device-dependent resolution. 
Spacing size must be large enough to accommodate character sizes on 
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affected output lines. For the common type sizes (9 through 12 points), 
usual typesetting practice is to set v to two points greater than the point 
size; trof f default is 10-point type on a 12-point spacing. The 
current v is available in the . v register. Multiple-v line separation (for 
example, double spacing) may be obtained with a . Is (line spacing) 
request. 

7.2 Extra line space 

If a word contains a vertically tall construct requiring the output line 
containing it to have extra vertical space before or after it or in both 
places, the extra line space function \x' n' can be embedded in or 
attached to that word. In this and in other functions having a pair of 
delimiters around their parameters, the delimiter choice is arbitrary 
except that it cannot look like the continuation of a number expression 
forn. 

• If n is negative, the output line containing the word will be 
preceded by n extra vertical spaces. 

• If n is positive, the output line containing the word will be 
followed by n extra vertical spaces. 

• If successive requests for extra space apply to the same line, the 
maximum value is used. 

The most recentiy used post-line extra line space is available in the .a 
register. 

7.3 Blocks of vertical space 

A block of vertical space is ordinarily requested using . sp, which 
honors the no-space mode and which does not space past a trap. A 
contiguous block of vertical space may be reserved using the . sv 
request. 

Note: Values separated by a semicolon (;) in the "Initial 
value"field below are for the nrof f and trof f formatters, 
respectively. 
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Request Initial If no _ , 

, ^ , ^Expanation 

form value argument ^ 

.Is [n] n=l previous Line spacing set to ±n. Output n-1 

blank lines (vs) after each output text 
line. If the text or previous appended 
blank line reached a trap position, 
appended blank lines are omitted. 
Relevant parameters are a part of the 
current environment. 

.ns space - Set no-space mode. The no-space 

mode inhibits . sp and . bp requests 
without a next page number. It is 
tumed off when a line of output occurs 
or with the . rs request. Mode or 
relevant parameters are associated with 
current diversion level. 

• OS - - Output saved vertical space. The 

request is used to output a block of 
vertical space requested by an earlier 
. sv request. The no -space mode 
( . ns) has no effect. 

• rs - - Restore spacing. The no-space mode 

( . ns) is tumed off. Mode or relevant 
parameters are associated with current 
diversion level. 

. sp [n] - n=lv Space vertically. The request provides 

spaces in either direction. If n is 
negative, the motion is backward 
(upward) and is limited to the distance 
to the top of the page. Forward 
(downward) motion is truncated to the 
distance of the nearest trap. If the no- 
space mode ( . ns) is on, no spacing 
occurs. The scale indicator is ignored 
if not specified in the request. The 
request causes a break. 
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Request Initial 
form value 

. sv [n] 



if no 
argument 



n=lv 



, vs [n] l/6in;12pts previous 



Blank line 



Explanation 

Save a contiguous vertical block of size 
n. If the distance to the next trap is 
greater than n, n vertical spaces are 
produced. If the distance to the next 
trap is less than n, no vertical space is 
immediately produced; but n is 
remembered for later output ( . os). 
Subsequent . sv requests overwrite any 
stUl remembered n. The no-space 
mode ( . ns) has no effect. The scale 
indicator is ignored if not specified in 
the request. 

Set vertical base-line spacing size v. 
Transient extra vertical spaces are 
available with \x' n' . The scale 
indicator is ignored if not specified in 
the request. Relevant parameters are a 
part of the current environment. 



This condition causes a break and 
output of a blank line (just as does 
1). 



sp 



8. Line length and indenting 

The maximum line length for fill mode may be set with a . 11 request. 
The indent may be set with a . in request; an indent applicable to only 
the next output line may be set with the . t i (temporary indent) 
request. 

The line length includes indent space but not page offset space. The 
line length minus the indent is the basis for centering with the . ce 
request. If a partially collected line exists, the effect of . 11, . in, or 
. ti is delayed until after that line is produced. In fill mode, the length 
of text on an output line is less than or equal to the line length minus 
the indent. 

The current line length and indent are available in registers . 1 and . i, 
respectively. The length of three-part titles produced by . 1 1 is 
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independently set by . It (see "Three-Part Titles"). 



Request 
form 



Initial If no 
value argument 



Explanation 



in [±n] n = previous 



11 [±n] 6.5 in previous 



ti ±n 



ignored 



Indent. The indent is set to ±n and 
prefixed to each output line. The scale 
indicator is ignored if not specified in 
the request. Relevant parameters are a 
part of the current environment. The 
request causes a break. 

Line length. The line length is set to 
±n. The scale indicator is ignored if 
not specified in the request. Relevant 
parameters are a part of the current 
environment. 

Temporary indent. The next output 
text line will be indented a distance ±n 
with respect to the current indent. The 
resulting total indent may not be 
negative. The current indent is not 
changed. The value of the current 
indent (stored in the . i register) is 
unchanged. The scale indicator is 
ignored if not specified in the request. 
Relevant parameters are a part of the 
current environment. The request 
causes a break. 



9. Macros, strings, diversions, and position traps 

9.1 Macros and strings 

A macro is a named set of arbitrary lines that can be invoked by name 
or with a trap. A string is a named string of characters, not including a 
newline character, that can be interpolated by name at any point. 
Request, macro, and string names share the same name Ust. Macro and 
string names may be 1- or 2-characters long and may usurp previously 
defined request, macro, or string names. Any of these entities may be 
renamed with . rn or removed with . rm. 
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• Macros are created by . de and . di and appended by . am and 
. da ( . di and . da cause normal output to be stored in a 
macro). 

• Strings are created by . ds and appended by .as. 

A macro is invoked in the same way as a request; a control line 
beginning .xx will interpolate the contents of macro xx. The remainder 
of the line can contain up to nine arguments. The strings x and xx are 
interpolated at any desired point with \ *x and \* {xx, respectively. 
String references and macro invocations can be nested within text. 

9.2 Copy mode input interpretation 

During the definition and extension of strings and macros in the current 
environment, the input is read in copy mode. The input is copied 
without interpretation except that: 

• Contents of number registers indicated by \n are interpolated. 

• Strings indicated by \* are interpolated (see "Macros and 
strings"). 

• Arguments indicated by \ $ are interpolated. 

• Concealed newline characters indicated by \<CR> are 
eliminated. 

• Comments indicated by \ " are eliminated (see "Comments and 
Concealed Newline Characters"). 

• \t and \a are interpreted as ASCII horizontal tab and start of 
heading (SOH), respectively (see "Tabs and Leaders"). 

• \\ is interpreted as "\". 

• \ . is interpreted as " . ". 

These interpretations can be suppressed by prefixing a \. For example, 
because \ \ maps into a \ , \ \n will copy as \n which will be 
interpreted as a number register indicator when the macro or string is 
reread. 

9.3 Arguments 

When a macro is invoked by name, the remainder of the line can 
contain up to nine arguments. The argument separator is the space 
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character, and arguments may be surrounded by double-quotes to 

permit embedded space characters. Pairs of double-quotes may be 

embedded in double-quoted arguments to represent a single double- / 

quote. If the desired arguments will not fit on a line, a concealed ^ 

newline character may be used to continue on the next line. 

When a macro is invoked, the input level is pushed down and any 
arguments available at the previous level become unavailable until the 
macro is completely read and the previous level is restored. A macro's 
own arguments can be interpolated at any point within the macro with 
\ $n, which interpolates the nth argument (1 < « < 9). If an invoked 
argument does not exist, a null string results. For example, the macro 
XX may be defined by 

.de XX \" begin definition 

Today is \\$1 the \\$2. 

\" end definition 

and called by 

.XX Monday 14th 
to produce the text ^ 

Today is Monday the 14th. 

The \ $ was concealed in the definition with a preceding backslash. 
The number of currently available arguments is in the . $ register. 

No arguments are available: 

• at the top (nonmacro) level in this implementation 

• from within a string because string referencing is implemented as 
an input-level pushdown 

• within a trap-invoked macro 

Arguments are copied in copy mode onto a stack where they are 

available for reference. The mechanism does not allow an argument to 

contain a direct reference to a long string (interpolated at copy time), 

and it is advisable to conceal string references (with an extra \) to / 

delay interpolation until argument reference time. ■ 
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9.4 Diversions 

Processed output may be diverted into a macro for purposes such as 
footnote processing or determining the horizontal and vertical size of 
some text for conditional changing of pages or columns. A single 
diversion trap can be set at a specified vertical position. The number 
registers . dn and . dl, respectively, contain the vertical and horizontal 
size of the most recently ended diversion. Processed text that is 
diverted into a macro retains the vertical size of each of its lines when 
reread in no-fill mode regardless of the current v. Constant-spaced 
( . cs) or emboldened ( . bd) text that is diverted can be reread 
correctly only if these modes are again or still in effect at reread time. 
One way to do this is to embed in the diversion the appropriate . cs or 
. bd request with the transparent mechanism described in 
"Transparent Throughput"). 

Diversions may be nested and certain parameters and registers are 
associated with the current diversion level (the top non-diversion level 
may be thought of as diversion level 0). These parameters and 
registers are 

• diversion trap and associated macro 

• no-space mode 

• internally saved marked place (see .mk and . rt) 

• current vertical place ( . d register) 

• current high- water text base line ( . h register) 

• current diversion name ( . z register). 

9.5 Traps 

Three types of trap mechanisms are available: 

• page trap 

• diversion trap 

• input-line-count trap. 

Macro-invocation traps can be planted using . wh requests at any page 
position including the top. This trap position can be changed using the 
. ch request. Trap positions at or below the bottom of the page have 
no effect unless or until moved to within the page or rendered effective 
by an increase in page length. Two traps may be planted at the same 
position only by first planting them at different positions and then 
moving one of the ti^aps; the first planted trap will conceal the second 
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unless and until the first one is moved. If the first planted trap is moved 
back, it again conceals the second trap. The macro associated with a 
page trap is automatically invoked when a line of text is generated 
whose vertical size reaches or sweeps past the trap position. Reaching 
the bottom of a page springs the top-of-page trap, if any, provided there 
is a next page. The distance to the next trap position is available in the 
. t register; if there are no traps between the current position and the 
bottom of the page, the distance returned is the distance to the page 
bottom. 

Macro-invocation traps, effective in the current diversion, can be 
planted using . dt requests. The . t register works in a diversion. If 
there is no subsequent trap, a large distance is returned. 

Request Initial If no _ , 

, ^ , . Explanation 

form value argument ^ 

■ a^"^ ^ \yy\ - -yy^ • • Append to macro xx (append version of 

.de). 

.as XX string - ignored Append sfrin^ to string xx (append 

version of .ds). 

• ch XX [n] - - Change trap location. Change the trap 

position for macro xx to be n. In the 
absence of n, the trap, if it exists, is 
removed. The scale indicator is 
ignored if not specified in the request. 

. da [xx] - end Divert and append to macro xx (append 

version of the . di request). Mode or 
relevant parameters are associated with 
current diversion level. 

.de XX \yy] - .yy=.. Define or redefine macro xx. The 

contents of the macro begin on the next 
input line. Input lines are copied in 
copy mode until the definition is 
terminated by a line begirming with 
.yy. The macro yy is then called. 
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Request 
form 



Initial if no 
value argument 



Explanation 



.di [xx] 



. ds XX string 



.dt [n] [xx] 



In the absence of yy, the definition is 
terminated by a line beginning with . . . 
A macro may contain . de requests 
provided the terminating macros differ 
or the contained definition terminator is 
concealed; . . can be concealed as 
\ \ . . which will copy as \ . . and be 
reread as . . . 

end Divert output to macro xx. Normal text 

processing occurs during diversion 
except that page offsetting is not done. 
The diversion ends when the request 
. di or . da is encountered without an 
argument; extraneous requests of this 
type should not appear when nested 
diversions are being used. Mode or 
relevant parameters are associated with 
cvirrent diversion level. 

ignored Define a string xx containing string. 
Any initial double-quote in string is 
stripped to permit initial blanks. 

°ff Install a diversion trap at position n in 

the current diversion to invoke macro 
XX. Another . dt wiU redefine the 
diversion trap. If no arguments are 
given, the diversion trap is removed. 
Mode or relevant parameters are 
associated with current diversion level. 
The scale indicator is ignored if not 
specified in the request. 

none End macro. Macro xx will be invoked 

when all input has ended. The effect is 
the same as if the contents of xc had 
been at the end of the last file 
processed. 
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Request 
form 



initial if no 
value argument 



Explanation 



.it [n] [xx] - off Input-line-count trap. An input-line- 

count trap is set to invoke the macro xx 
after n lines of text input have been 
read (control or request lines do not 
count). Text may be in-line or 
interpolated by in-line or trap-invoked 
macros. Relevant parameters are a part 
of the current environment. 

. rm xx - ignored Remove. A request, macro, or string is 

removed. The name xx is removed 
from the name list and any related 
storage space is freed. Subsequent 
references have no effect. 

.rn XX yy - ignored Rename. Rename request, macro, or 

string from xx to yy. If yy exists, it is 
first removed. 

• wh n [xx] - - When. A location trap is set to invoke 

macro xx at page position n; a negative 
n is interpreted with respect to the page 
bottom. Any macro previously planted 
at n is replaced by xx. A zero n refers 
to the top of a page. In the absence of 
xx, the first found trap at n, if any, is 
removed. The scale indicator is 
ignored if not specified in the request. 

10. Number registers 

A variety of predefined number registers are available to the user. In 
addition, the user may define his own named registers. Register names 
are 1- or 2-characters long and do not conflict with request, macro, or 
string names. Except for certain predefined read-only number 
registers, a number register can be read, written, automatically 
incremented or decremented, and interpolated into the input in a variety 
of formats. One common use of user-defined registers is to 
automatically number sections, paragraphs, lines, and so on. A number 
register can be used any time numeric input is expected or desired and 
can be used in numeric expressions. 



3-28 



A/UX Text Processing Tools 



Number registers are created and modified using the , nr request, 
which specifies name, numeric value, and automatic increment size. 
Registers are also modified if invoked with an automatic incrementing 
sequence. If the registers x and xx both contain n and have the 
automatic increment size m, the following access sequences have the 
effect shown: 



Sequence 


Effect on 
register 


Value 
Interpolated 


nx 

n(xx 

n+x 

n-x 

n+(xx 

n-(xc 


none 

none 

X incremented by m 

X decremented by m 

XX incremented by m 

XX decremented by m 


n 

n 

n+m 

n-m 

n+m 

n-m 



According to the format specified by the . af request, a number 
register is converted (when interpolated) to 

• decimal (default) 

• decimal with leading zeros 

• lowercase roman 

• uppercase roman 

• lowercase sequential alphabetic 

• uppercase sequential alphabetic 

The escape sequence "\gx" or "\g (xc" gives the format used by the 
registers x or xx. This escape sequence will only return a value if the 
stated register has been set or used; otherwise, it returns 0. The value 
can also be saved and used as the second argument of . af to restore a 
previous format. 
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Request Initia If no _ , ^, 

, ^ , ^ Explanation 

form value argument ^ 

. af r c Arabic - Assign format. Format c is assigned to 

register r. Available formats are: 

1 0,1,2,... 
001000,001,002,... 
i 0,i,ii,... 

I o,i,n,... 

a 0,a,b,...,z aa,ab,...,zz aaa,... 

A 0,A,B,...,Z AA,AB ZZ 

AAA,... 

An Arabic format having n digits 
specifies a field width of n digits. 
Read-only registers and width function 
are always Arabic. 

.nr r ±n m - - Number register. The number register 

r is assigned the value ±n with respect 
to the previous value, if any. The 
automatic incrementing value is set to 
m. The number register value (n) is 
ignored if not specified in the request. 

• rr r - - Remove register. The number register 

r is removed. If many registers are 
being created dynamically, it may be 
necessary to remove registers that are 
no longer used in order to recapture 
internal storage space for newer 
registers. 

1 1 . Tabs, leaders, and fields 
1 1 .1 Tabs and leaders 

Both the ASCII horizontal tab character and the ASCII SOH character 
(the leader) can be used to generate either horizontal motion or a string 
of repeated characters. The length of the generated entity is governed 
by internal tab stops specified with a . ta request. The default 
difference is that tabs generate motion and leaders generate a string of 
periods; . tc and . Ic offer the choice of repeated character or motion. 
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There are three types of internal tab stops: left justified, right justified, 
and centered. In the following table, 

• next-string consists of the input characters following the tab (or 
leader) up to the next tab (or leader) or end of line. 

• <i is the distance from the current position on the input line 
(where a tab or leader was found) to the next tab stop. 

• w is the width of next-string. 



Tab 
type 


Length of motion or 
repeated characters 


Location of 

next-string 


Left 

Right 

Centered 


d 

d-w 
d-wl2 


Following d 

Right justified within d 

Centered on right end of d 



The length of generated motion is allowed to be negative but that of a 
repeated character string cannot be. Repeated character strings contain 
an integer number of characters, and any residual distance is prefixed 
as motion. Tabs or leaders found after the last tab stop are ignored, but 
they may be used as next-string terminators. 

Tabs and leaders are not interpreted in copy mode. The \t and \a 
always generate an uninterpreted tab and leader, respectively, and are 
equivalent to actual tabs and leaders in copy mode. 

11.2 Fields 

A field is contained between a pair of field delimiter characters. It 
consists of substrings separated by padding indicator characters. The 
field length is the distance on the input line from the position where the 
field begins to the next tab stop. The difference between the total 
length of all the substrings and the field length is incorporated as 
horizontal padding space that is divided among the indicated padding 
places. The incorporated padding is allowed to be negative. For 
example, if the field delimiter is # and the padding indicator is " , then 

#"xxx"right# 

specifies a right-justified string with the string xxx centered in the 
remaining space. 
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Note: Values separated by a semicolon (;) in the "Initial 
value"field below are for the nrof f and trof f formatters, 
respectively. 



Request 
fornn 



Initial 
value 



If no 
argument 



Explanation 



fc [a] [b] off 



off 



Ic [c] 



. ta nt... 



8n;0.5 in none 



.tc [c] 



Field delimiter is set to a. The padding 
indicator is set to the space character or 
to b, if given. In the absence of 
arguments, the field mechanism is 
turned off. 

Leader repetition character becomes c 
or is removed specifying motion. 
Relevant parameters are a part of the 
current environment. 

Set tab stops and types. The 
adjustment within the tab is as follows: 

type result 

R right 

C centering 

absent left 

Tab stops for the trof f formatter are 
preset every 0.5 inch; Tab stops for the 
nrof f formatter are preset every eight 
nominal character widths. Stop values 
are separated by spaces, and a value 
preceded by + is treated as an 
increment to the previous stop value. 
Relevant parameters are a part of the 
current envirormient. The scale 
indicator is ignored if not specified in 
the request. 

Tab repetition character becomes c or is 
removed specifying motion. Relevant 
parameters are a part of the current 
envirormient. 
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12. Input/output conventions and character 
translations 

1 2.1 Input character translations 

The newline character delimits input lines. In addition, STX, ETX, 
ENQ, ACK, and BEL are accepted and can be used as delimiters or 
translated into a graphic with a . tr request. All others are ignored. 

The escape character (\) introduces sequences that indicate some 
function such as a font change or the printing of a special character. 
The escape character 

• should not be confused with the ASCII control character ESC of 
the same name 

• can be input with the sequence \ \ 

• can be changed with . ec, and all that has been said about the 
default \ becomes true for the new escape character. 

A \e sequence can be used to print the current escape character. If 
necessary or convenient, the escape mechanism can be turned off with 
. eo and restored with . ec. 

12.2 Ligatures 

Twoligaturesareavailableinthetr off character set: fi and fl. 
They may be entered (even in the nrof f formatter) by \ ( f i and 
\ ( f 1, respectively. Note that ligature mode is normally on in the 
trof f formatter; that is, ligatures are automatically produced. 
Constant-width fonts normally do not use ligatures. 

12.3 Bacl<spacing, underlining, and overstrilcing 

Unless in copy mode, the ASCII backspace character is replaced by a 
backward horizontal motion having the width of the space character. 
Underlining as a form of line drawing and, as a generalized 
overstriking function, is described in "Overstrike, Zero-Width, 
Bracket, and Line Drawing Functions." 

The nrof f processor underlines characters automatically in the 
underline font, specifiable with the .uf request. The underline font is 
normally on font position 2 (Times Italic). In addition to . ft request 
and \f/ escape sequence, the underline font may be selected by . ul 
and . cu requests. Underlining is restricted to an output-device- 
dependent subset of reasonable characters. 
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12.4 Control characters 

Both the break control character ( . ) and the no-break control character 
( ' ) may be changed, if desired. Such a change must be compatible 
with the design of any macros used in the span of the change and 
particularly with any trap-invoked macros. 

12.5 Output translation 

One character can be made a stand-in for another character using the 
. t r request. All text processing (for example, character comparisons) 
takes place with the input (stand-in) character which appears to have 
the width of the final character. Graphic translation occurs at the 
moment of output (including diversion). 

Note: Values separated by a semicolon (;) in the "Initial 
value"field below are for the nrof f and trof f formatters, 
respectively. 



Request Initial If no _ , .. 

, ^ , . Explanation 

form value argument ^ 

• cc [c] . . Set control character to c or reset to . . 

Relevant parameters are a part of the 
current environment. 

.cu [n] off n=:l Continuous underline in the nroff 

formatter. A variant of . ul that causes 
every character to be underlined. 
Identical to . ul in the trof f 
formatter. Relevant parameters are a 
part of the current enviroimient. 

■ ^2 [c] ' ' Set no-break control character to c or 

reset to ' . Relevant parameters are a 
part of the current environment. 

. ec [c] \ \ Set escape character to \ or to c if 

given. 

•eo on - Turn escape character mechanism off . 
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Request Initial If no _ , 

. ^ , . Explanation 

form value argument ^ 



- Ig [«] off;(Mi on Ligature mode is turned on if n is 

absent or nonzero and turned off if n=0. 
If n=2, only the 2-character ligatures 
are automatically invoked. Ligature 
mode is inhibited for request, macro, 
string, register, file names, and copy 
mode. There is no effect in then roff 
formatter. 

• tr abed. . . none - Translate a into b, c into d, and so forth 

on output. If an odd number of 
characters is given, the last one will be 
mapped into the space character. To be 
consistent, a particular translation must 
stay in effect from input to output time. 
Initially there are no translate values. 

. u f / Italic ItaUc Underline font set to / (to be switched 

to by . ul). In the nrof f formatter/ 
may not be on position 1 (initially 
Times Roman). 

.ul [n] off n=l Underline in the nrof f formatter 

(italicize in t roff ) the next n input 
text lines. Switch to underline font 
saving the current font for later 
restoration; other font changes within 
the span of a . ul will take effect, but 
the restoration will undo the last 
change. Output generated by .tlis 
affected by the font change but does 
not decrement n. If n is greater than 1, 
there is the risk that a trap interpolated 
macro may provide text lines within the 
span, which environment switching can 
prevent. Relevant parameters are a part 
of the current environment. 
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12.6 Transparent throughput 

An input line beginning with a \ ! is read in copy mode and 
transparently output (without the initial \ ! ); the text processor is 
otherwise unaware of the line's presence. This mechanism may be 
used to pass control information to a post-processor or to embed 
control lines in a macro created by a diversion. 

12.7 Comments and concealed newline characters 

An unusually long input line that must stay one line (for example, a 
string definition or no-filled text) can be spUt into many physical lines 
by ending all but the last one with the escape character (\). The 
sequence \<CR> is ignored except in a comment. Comments can be 
embedded at the end of any line by prefacing them with \ " . The 
newline character at the end of a comment cannot be concealed. A line 
beginning with \ " will appear as a blank line and behave like . sp 1; 
a comment can be on a line by itself by beginning the line with . \ " . 

13. Local horizontal/vertical motion and width 

13.1 Local motion 

The functions \v' n' and \h' n' can be used for local vertical and 
horizontal motion, respectively. The distance n may be negative; the 
positive directions are rightward and downward. A local motion is one 
contained within a line. To avoid unexpected vertical dislocations, it is 
necessary that the net vertical local motion (within a word in filled text 
and otherwise within a line) balance to zero. 

As an example, E is generated by the sequence 

E\v'-.5'\s-4\&2\sO\v' .5' 

13.2 Width function 

The width function \w' string' generates the numeric width of string 
in basic units. Size and font changes may be embedded in string and 
will not affect the current environment. For example, 

• ti -Xw'iyu 

could be used to temporarily indent leftward a distance equal to the size 
ofthe string"!.". 

The width function also sets three number registers. The registers st 
and sb are set respectively to the highest and lowest extent of string 
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relative to the baseline; then, for example, the total height of the string 
is \n (stu-\n (sbu. In the trof f formatter, the number register ct 
is set to a value between and 3: 

• means that all characters in string are short lowercase 
characters without descenders (like the character e) 

• 1 means that at least one character has a descender (like the 
character y) 

• 2 means that at least one character is tall (like the character h) 

• 3 means that both tall characters and characters with descenders 
are present 

13.3 Mark horizontal place 

The escape sequence \lcc will cause the current horizontal position in 
the input line to be stored in register x. As an example, the 
construction: 

\kx\f Iword\fR\h' | \nxu+2u' \f Iword\fR 

will embolden word by backing up to almost its beginning and 
overprinting it, resulting in 

word 

14. Overstrike, zero-width, bracket, and line 
drawing functions 

14.1 Overstrike 

Automatically centered overstriking of up to nine characters is 
provided by the overstrike function \o ' string' . Characters in string 
are overprinted with centers aligned; the total width is that of the 
widest character. The string should not contain local vertical motion. 
For example: 

\o'e\ '' produces e 

\o'>/' produces i- 

14.2 Zero-width characters 

The function \zc will generate c without spacing over it and can be 
used to produce left-aligned overstruck combinations. 
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14.3 Large brackets 

The Special Mathematical Font contains a number of bracket 
construction pieces that can be combined into various bracket styles. 
The function \h' string' can be used to pile up vertically the 
characters in string (the first character on top and the last at the 
bottom); the characters are vertically separated by one em and the total 
pile is centered one-half em above the current base line (one-half line 
in the nrof f formatter). For example: 

\h'\ (lc\(lf'\|E\|\b'\ (rc\ (rf'\x'-0.5m'\x'0.5m^ 

produces 



14.4 Line drawing 

The \1' nc' function will draw a string of repeated c's toward the 
right for a distance n (1 is lowercase L). 

• If c looks like a continuation of an expression for n, it can be 
insulated from n with a \&. 

• If c is not specified, the base-line rule (_) is used (underline 
character in nrof f ). 

• If n is negative, a backward horizontal motion of size n is made 
before drawing the string. 

Any space resulting from n/(size of c) having a remainder is put at the 
beginning (left end) of the string. In the case of characters that are 
designed to be connected, such as base-line rule (_), underrule (\ (ul), 
and root en (\ ( ru), the remainder space is covered by overlapping. If 
n is less than the width of c, a single c is centered on a distance n. As 
an example, a macro to underscore a string can be written 

• de us 
\\$1\1' |0\(ul' 

or a macro can draw a box around a string: 
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.de bx 

\ (br\ I \\$1\ I \ (br\l' I 0\ (rn' \1' | 0\ (ul' 

such that 

.us "underlined words" 
and 

.bx "words in a box" 

yield 

underlined words 
and 



[ words in a box] 

The function \l' nc' will draw a vertical line consisting of the 
optional character c stacked vertically apart one em (one line in 
nrof f), with the first two characters overlapped, if necessary, to form 
a continuous line. The default character is box rule (\ (br); the other 
suitable character is bold vertical (\ (bv). The line is begun without 
any initial motion relative to the current base line. A positive n 
specifies a line drawn downward, and a negative n specifies a line 
drawn upward. After the line is drawn, no compensating motions are 
made; the instantaneous base line is at the end of the line. 

The horizontal and vertical line drawing functions may be used in 
combination to produce large boxes. The zero-width box-rule and the 
one-half em wide undemile were designed to form comers when using 
one em vertical spacings. For example, the macro 

. de eb 

. sp -11 \"compensat.e for automatic base-line spacing 

.nf \"avold possibly overflowing word buffer 

\h' - . 5n ' \L' I Wnau-l ' \1 ' \\n ( . lu+ln\ (ul ' \L' - 1 \\nau+l ' \ 

\1' |0u-.5n\ (ul' \" draw box 

.fl 

will draw a box around some text whose beginning vertical place was 
saved in number register a (for example, using . mk a). 
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In addition, trof f provides drawing functions capable of drawing 
arcs and splines. 

Request _ , 

, ^ Explanation 

form 

\D ' 1 dh dv' Draw a line for the current position by dh, dv. 

\D ' c d' Draw a circle of diameter d with its left side 

at the current position. 

\D ' e dl d2' Draw an ellipse of diameters dl and d2 with 

its left side at the current position. 

\D'a dhl dvl dh2 dv2' Draw a counterclockwise arc from the current 

position to dhJ+dh2, dvl+dv2, with its center 
at dhl, dvl from the current position. 

\D'~ dhl dvl dh2 dv2...' Draw a B-spline from the current position by 

dhl, dvl, then by dh2, dv2, then . . . 

The current position after using these drawing functions is at the end of 
the drawn line, which for circles and ellipses is at the right side. 

15. Hyphenation 

The automatic hyphenation may be switched off and on. When 
switched on with . hy, several variants may be set. A hyphenation 
indicator character may be embedded in a word to specify desired 
hyphenation points or may precede a word to suppress hyphenation. In 
addition, the user may specify a small exception word list. The default 
condition of hyphenation is off. 

Only words that consist of a central alphabetic string surrounded by 
nonalphabetic strings (usually null) are considered candidates for 
automatic hyphenation. Words that were entered containing hyphens 
(minus), em-dashes (\ (em), or hyphenation indicator characters (such 
as mother-in-law) are always subject to splitting after those characters 
whether or not automatic hyphenation is on or off. 
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Request 
form 



Initial 
value 



If no 
argument 



Explanation 



.he [c] 



.hw wordl. 



■ hy [«] 



.nh 



\* \* Hyphenation character. Hyphenation 

indicator character is set to c or to the 
default \%. The indicator does not 
appear in the output. Relevant 
parameters are a part of the current 
environment. 

ignored Exception words. Hyphenation points 
in words are specified with embedded 
minus signs. Versions of a word with 
terminal s are implied; that is, dig -it 
implies dig-its. This list is examined 
initially and after each suffix stripping. 
Space available is small — about 128 
characters. 

off,n=0 on,«=l Hyphenate. Automatic hyphenation is 

turned on for n>l or off for n=0. If 
n=2, last lines (ones that will cause a 
trap) are not hyphenated. For n=4 the 
last two characters of a word are not 
divided. For n=8 the first two 
characters of a word are not divided. 
These values are additive; that is, n=14 
invokes all three restrictions. Relevant 
parameters are a part of the current 
environment. 

no hyphen - No hyphenation. Automatic 

hyphenation is turned off. Relevant 
parameters are a part of the current 
environment. 



16. Three-part titles 

The titling function , 1 1 provides for automatic placement of three 
fields at the left, center, and right of a line with a title length specifiable 
with . It. The . 1 1 may be used anywhere and is independent of the 
normal text collecting process. A common use is in header and footer 
macros. 
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Request Initial 
form value 



If no 
argument 



Explanation 



.It [±n] 6.5 in 



.pc [c] % 



previous 



off 



Length of title set to +n. Line length 
and title length are independent. 
Indents do not apply to titles; page 
offsets do. Relevant parameters are a 
part of the current environment. The 
scale indicator is ignored if not 
specified in the request. 

Page number character set to c or 
removed. The page number register 



.tl'left' center' right ' 



Three-part title. The strings left, center, 
and right are respectively left-adjusted, 
centered, and right-adjusted in the cvirrent 
title length. Any of the strings may be 
empty, and overlapping is permitted. If 
the page number character (initially %) is 
found within any of the fields, it is 
replaced by the current page number 
having the format assigned to register %. 
Any character may be used as the string 
delimiter. 



17. Output line numbering 

Automatic sequence numbering of output lines can be requested with 
. nm. When in effect, a three-digit, Arabic number plus a digit-space is 
prefixed to output text lines. Text lines are offset by four digit-spaces 
and otherwise retain their line length. A reduction in line length may 
be desired to keep the right margin aligned with an earlier margin. 
Blank lines, other vertical spaces, and lines generated by . tl are not 
numbered. Numbering can be temporarily suspended with . nn or with 
a . nm followed by a later .nm +0. In addition, a line number indent / 
and the number-text separation s can be specified in digit-spaces. 
Further, it can be specified that only those line numbers that are 
multiples of some number m are to be printed (the others will appear as 
blank number fields). 
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Request Initial If no _ , 

, ^ , . Explanation 

form value argument ^ 



. nm [±n] [m] ' off Line number mode. If ±n is given, line 

[s] [i] nvimbering is turned on, and the next 

output line is numbered +n. Default 
values are m=l, s=l, and t=0. 
Parameters corresponding to missing 
arguments are unaffected; a non- 
ntimeric argument is considered 
missing. In the absence of all 
arguments, numbering is turned off, 
and the next line number is preserved 
for possible further use in number 
register In. Relevant parameters are a 
part of the current environment. 

. nn [n] - n=\ Next n lines are not numbered. 

Relevant parameters are a part of the 
current environment. 

The following illustrates output line numbering. Paragraph portions 
are numbered with m=2. 

Automatic sequence numbering of output lines may be requested 
2 with . nm. When in effect, a 3-digit, Arabic number plus a digit- 
space is prefixed to output text lines. Text lines are offset by four 
4 digit-spaces and otherwise retain their line length. A reduction in 
line length (such as. 11 -\w'0000'uin this example) may be 
6 desired to keep the right margin aligned with an earlier margin. 

Blank lines, other vertical spaces, and lines generated by . tl are 
8 not numbered. Numbering can be temporarily suspended with 
. nn or with a . nm followed by a later . nm + . 

10 In addition, a line number indent / and the number-text separation 
s may be specified in digit-spaces. Further, it can be specified that 

12 only those line numbers that are multiples of some number m are 
to be printed (the others will appear as blank number fields). This 
example uses the multiple of 2. 

• .11 -Xw'OOOO'u was placed at the beginning to keep the 
right margin aligned 
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• . nm 1 2 was placed at the beginning 

• . nm +0 was placed in front of the second and third paragraphs 

• . nm was placed at the end 

• .11 +\w' 0000' u was placed at the end to return to the 
original line length 

Another example is 

.nm +55x3 

which turns on numbering with the line number of the next line to be 
filve greater than the last numbered line, with m=5, spacing s 
untouched, and the indent i set to 3. 

18. Conditional acceptance of input 

In the table below, which is a summary and explanation of conditional 
acceptance requests: 

• c is a 1 -character, built-in condition name. 

• ! signifies «£>/. 

• « is a numeric expression. 

• string! and string! are strings delimited by any nonblank, non- 
numeric character not in the strings. 

• anything represents what is conditionally accepted. 



Request 
form 



Explanation 



el anything The "else" portion of "if -else". 

ie c anything The "if" portion of "if-else." Thee can 

be any of the forms acceptable with the 
. i f request. 

if c anything Ifcondition c true, accept anyr/zj«g as 

input; for multiline case, use 
\ { anything\ } . The scale indicator is 
ignored if not specijBed in the request. 

if \c anything If condition c false, accept an^jf/i/n^. 
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Request 
form 

• if n anything 



.if !n anything 



Explanation 

If expression n > 0, accept anything. The 
scale indicator is ignored if not specified in 
the request. 

If expression n < accept anything. The 
scale indicator is ignored if not specified in 
the request. 

• if ' string 1 ' string! ' anything 

If string 1 is identical to string!, accept 
anytlung. 

• if ! ' string 1 ' string! ' anything 

If string 1 is not identical to string!, accept 
anything. 

The built-in condition names are 



Condition 
name 


True if 


o 
e 

t 
n 


Current page number is odd 
Current page number is even 
Formatter is tr off 
Formatter is nroff 



If condition c is true, if number n is greater than zero, or if strings 
compare identically (including motions and character size and font), 
anything is accepted as input. If a ! precedes the condition, number, or 
string comparison, the sense of the acceptance is reversed. 

Any spaces between the condition and the beginning of anything are 
skipped over. The anything can be either a single input line (text, 
macro, or whatever) or a number of input Unes. In the multiline case, 
the first line must begin with a left deUmiter \ { and the last line must 
end with a right dehmiter \ } . 

The request . ie (if-else) is identical to . if except that the acceptance 
state is remembered. A subsequent and matching . el (else) request 
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then uses the reverse sense of that state. The . ie - .el pairs may be 
nested. For example 

.if e .tl ' Even Page %' ' ' 

generates a title if the page number is even, and 

.ie \n%>l\{\ 
'sp 0.5i 
.tl 'Page %'" 
'sp |1.2i\} 
.el .sp|2.5i 

treats page 1 differenfly from other pages. 

19. Environment switching 

A number of parameters that control text processing are gathered 
together into an environment, which can be switched by the user. 
Environment parameters are those associated with some requests. The 
request tables in this chapter indicate in the Explanation column those 
requests so affected. In addition, partially collected lines and words are 
in the environment. Everything else is global; examples are page- 
oriented parameters, diversion-oriented parameters, number registers, 
and macro and string definitions. All environments are initialized with 
default parameter values. 

Request Initial If no _ , 

, ^ , . Explanation 

form value argument ^ 

.ev [n] n = previous Environment switched to 0, 1, or 2. Switching 

is done in pushdown fashion so that restoring a 
previous environment must be done with . ev 
rather than specific reference. 

20. Insertions from standard input 

The input can be switched temporarily to the system standard input 
with . rd and switched back when two newline characters in a row are 
found (the extra blank line is not used). This mechanism is intended 
for insertions in form-letter-like documentation. On the AAJX 
operating system, the standard input can be the user keyboard, a pipe, 
or a file. 
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If insertions are to be taken from the terminal keyboard while output is 
being printed on the terminal, the flag option -q will turn off the 
echoing of keyboard input and prompt only with BEL. The regular 
input and insertion input cannot simultaneously come from the standard 
input. As an example, multiple copies of a form letter can be prepared 
by entering insertions for all copies in one file to be used as the 
standard input and causing the file containing the letter to reinvoke 
itself by using the .nx request. The process would be ended by a .ex 
request in the insertion file. 



Request 
form 



Initial If no 
value argument 



Explanation 



, rd \prompi\ 



Exit from the n ro f f /t r o f f 
formatter. Text processing is 
terminated exactly as if all input had 
ended. 

prompt=SEL Read insertion from the standard input 
until two newline characters in a row 
are found. If standard input is the user 
keyboard, a. prompt (or a BEL) is 
written onto the user terminal. The 
request behaves like a macro; 
arguments may be placed after prompt. 



21. Input/output file switching 



Request 
form 



Initial If no 
value argument 



Explanation 



. cf filename 



.nx [filename] 



end-of-file 



Copy the contents affile, uninterpreted 
into trof f output file at this point. 
Havoc ensues unless the motions in the 
file restore the current horizontal and 
vertical position. 

Next Gie is filename. The current file is 
considered ended, and the input is 
immediately switched to filename. 
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Request 
form 



Initial If no 
value argument 



Explanation 



.pi program 



, so filename 



.If n file 



Pipe output to program. This request 
must occur before any printing occurs. 
No arguments are transmitted to 
program. 

Switch source file (pushdown). The 
top input level (file reading) is switched 
Vo filename. Contents are interpolated 
at the point the request is encountered. 
When the new file ends, input is again 
taken from the original file. The . so 
requests may be nested. 

Corrects t rof f 's idea of the current 
Une number, n, and the current file, file, 
for use in error messages 



22. Miscellaneous 



Request 
form 



Initial If no 
value argument 



Explanation 



.fi 



• ig \yy\ 



Flush output buffer. Used in interactive 
debugging to force output. The request 
causes a break. 

■yy = -- Ignore input lines until call of yy. This 
request behaves like the . de request 
except that the input is discarded. The 
input is read in copy mode, and any 
automatically incremented registers will 
be affected. 
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Request Inta If no _ , ., 

, ^ , . Explanation 

form value argument ^ 



■ ^^ <^ ["] - o^f Sets margin character c and separation n. 

Specifies that a margin character c appear 
a distance n to the right of the right 
margin after each nonempty text line 
(except those produced by . 1 1). If the 
output hne is too long (as can happen in 
no-fill mode), the character wiU be 
appended to the line. If n is not given, 
the previous n is used; the initial n is 0.2 
inches in the nrof f fonnatter and 1 em 
in trof f . Relevant parameters are a 
part of the current environment. The 
scale indicator is ignored if not specified 
in the request. 

■ P^ W - ^ Print macros. The names and sizes of all 

defined macros and strings are printed on 
the user terminal. If f is given, only the 
total of the sizes is printed. Sizes are 
given in blocks of 128 characters. 

• sy cmd orgs - - cmd is executed but its output is not 

captured at this point. The standard input 
for cmd is closed. Output for processing 
must be expUcitly saved in an output file. 

■ tm [string] - newline Pnnt string on terminal (AAJX operating 

system standard message output). After 
skipping initial blanks, string (rest of the 
line) is read in copy mode and written on 
the user terminal. 

23. Output and error messages 

Output from ,tm, . pm, and prompt from . rd, as well as various error 
messages are written onto the AAJX operating system standard 
message output. The latter is different from the standard output, when 
compared to the nrof f formatted output. By default, both are written 
onto the user's terminal, but they can be independently redirected. 
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Various error conditions can occur during the operation of the nrof f 
and trof f formatters. Certain less serious errors having only local 
impact do not cause processing to terminate. Two examples are 

• word overflow - caused by a word that is too large to fit into 
the word buffer (in fill mode). 

• line overflow - caused by an output line that grew too large 
to fit in the line buffer. 

In both cases, a message is printed, the offending excess is discarded, 
and the affected word or line is marked at the point of truncation with a 
* (in nrof f) or a => (in trof f). The usual procedure is to continue 
processing, if possible, on the grounds that output useful for debugging 
may be produced. If a serious error occurs, processing terminates, and 
an appropriate message is printed. Error conditions that can cause this 
include the inability to create, read, or write files, and the exceeding of 
certain internal limits that make future output unlikely to be useful. 

Request Initial If no _, , 

, ^ , . Explanation 

form value argument ^ 

. ab [text] - - Prints text on the message output and 

terminates without further processing. If 
fexf is missing, User Abort, is 
printed. This request does not cause a 
break. The output buffer is flushed. 
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24. Reference tables 

24.1 Escape sequences for characters, indicators, and 
functions 



Escape 


Meaning 


sequence 




W 


\ (to prevent or delay the interpretation of \) 


\e 


Printable version of current escape character 


\' 


Acute accent (equivalent to \ (aa) 


\^ 


Grave accent (equivalent to \ (ga) 


\- 


— (minus sign in the current font) 


\. 


Period (dot) 


\ Space 


Unpaddable space-size space character 


\0 


Unpaddable digit width space 


\l 


1/6 em narrow space character (zero width in nrof f ) 


\^ 


1/12 em half-narrow space character (zero width in nrof f ) 


\& 


Nonprinting zero width character 


\! 


Transparent line indicator 


\" 


Beginning of comment 


\$n 


Interpolate argument (l<n<9) 


\% 


Default optional hyphenation character 


\(xx 


Character named xx 


\*X,\* {XX 


Interpolate string x or xx 


\{ 


Begin conditional input 


\} 


End conditional input 


\<CR> 


Concealed (ignored) newline character 


\a 


Uninterpreted leader character 


\h'abc../ 


Bracket building function 


\c 


Continuation of interrupted text 


\d 


Forward (down) V2 em vertical motion {V2 line in nrof f ) 


\D 


Line-drawing functions 


\fx,\f (xxAfn 


Change to font named x or xx or position n 


\gx,\g(x«c 


Return the . a f -type format of the register x or xx 




(returns nothing if x or xx: has not yet been referenced) 



Note: Escape sequences \\, \., \", \$, \*, \a, \n, \t, \<CR> are 
interpreted in copy mode. 
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Escape 


Meaning 


sequence 




\h'n' 


Local horizontal motion, move right n (negative left) 


\H'n' 


Height control of characters (does not affect width). 


\k;c 


Mark horizontal input place in register x 


\l'nc' 


Horizontal line drawing function (optionally with c) 


\L'nc' 


Vertical line drawing function (optionally with c) 


\nx,\n {XX 


Interpolate number register xotxx 


\o'abc...' 


Overstrike characters a, b,c... 


\P 


Break and spread output line 


\r 


Reverse 1 em vertical motion (reverse line in nrof f ) 


\sn,\s±n 


Point-size change function 


\t 


Uninterpreted horizontal tab 


\u 


Reverse (up) V2 em vertical motion (V2 line in nrof f ) 


\v'n' 


Local vertical motion, move down n (negative up) 


\w' string' 


Interpolate width of string 


\x'n' 


Extra line-space function (negative before, positive after) 


\zc 


Print c with zero width (without spacing) 


U 


Any character not listed above 



Note: Escape sequences \\, \., \", \$, \*, \a, \n, \t, \<CR> are 
interpreted in copy mode. 
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24.2 Naming conventions for special characters on 
the standard fonts 



Char '"P"* 


Character 


Char 


Input 


Character 


name 


name 




name 


name 


» f 


Close quote 


Vi 


\(12 


One-half 


* 


Open quote 


Va 


\(34 


Three-fourths 


— \ (em 


% Em dash 


fi 


\(fi 


fi 


- 


Hyphen or 


fl 


\(fl 


fl 


- \(hy 


Hyphen 


o 


\(de 


Degree 


- \- 


Current font minus 


t 


\(dg 


Dagger 


• \(bu 


Bullet 


/ 


\{fm 


Foot mark 


n \(sq 


Square 





\(ct 


Cent sign 


_ \(ru 


Rule 


® 


\(rg 


Registered 


Va \(14 


One-fourth 


© 


\(co 


Copyright 
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24.3 Naming conventions for Greek cliaracters on tiie 
speciai font 



Chsr 


Input 


Character 


Char 


Input 


Character 




name 


name 




name 


name 


A 


\(*A 


Alphat 


a 


\(*a 


alpha 


B 


\(*B 


Betat 


P 


\(*b 


beta 


r 


\(*G 


Gamma 


Y 


\(*g 


gamma 


A 


\(*D 


Delta 


6 


\(*d 


delta 


E 


\(*E 


Epsilonf 


8 


\(*e 


epsilon 


Z 


\(*z 


Zetat 


c 


\(*z 


zeta 


H 


\(*Y 


Etat 


^ 


\(*y 


eta 





\(*H 


Theta 


e 


\(*h 


theta 


I 


\(*I 


lotat 


I 


\(*i 


iota 


K 


\(*K 


Kappat 


K 


\(*k 


kappa 


A 


\(*L 


Lambda 


X 


\(*1 


lambda 


M 


\(*M 


Mut 


^i 


\(*m 


mu 


N 


\(*N 


Nut 


V 


\(*n 


nu 


S 


\(*c 


Xi 


^ 


\(*c 


xi 


O 


\(*o 


Omicront 





\(*o 


omicron 


n 


\(*P 


Pi 


TC 


\{*P 


pi 


p 


\(*R 


Rhot 


P 


\(*r 


rho 


z 


\(*s 


Sigma 


CT 


\(*s 


sigma 








<; 


\(ts 


terminal sigma 


T 


\(*T 


Taut 


T 


\(*t 


tau 


Y 


\(*u 


Upsilon 


X> 


\(*u 


upsilon 


O 


\(*F 


Phi 


<t) 


\(*f 


phi 


X 


\(*x 


Chit 


X 


\(*x 


chi 


^ 


\(*Q 


Psi 


¥ 


\(*q 


psi 


a 


\(*W 


Omega 


(0 


\(*w 


omega 



t Mapped into uppercase English letters in the font mounted on font position 
one. 
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24.4 Naming conventions for special cliaracters on the 
special font 



Chai 


. Input Character 


Chai 


, Input Character 




name name 




name name 


+ 


\ (pi math plus 


* 


\ (** "math star" 


- 


\ (mi math minus 


1 


\ (or or 


± 


\ (+- plus-minus 


/ 


\ (si slash 


X 


\ (mu multiply 


§ 


\ (sc section 


-i- 


\ (di divide 


" 


\ (aa acute accent 


= 


\ (eq math equals 


- 


\ (ga grave accent 


> 


\ ( >= greater than or equal 




\ (ul undemile 


< 


\ (<= less than or equal 


— > 


\ ( -> right arrow 


= 


\ (== identically equal 


<r- 


\ (<- left arrow 


~ 


\ (~= approximately equal 


T 


\ (ua up arrow 


~ 


\ (ap approximates 


i 


\ (da down arrow 


^ 


\ ( ! = not equal 


t 


\ (dd double dagger 


V 


\ (sr square root 


¥ 


\ (bs "Bell System logo" 




\ ( rn root en extender 


<= 


\(lh "left hand" 


u 


\ (cu cup (union) 


=> 


\ (rh "right hand" 


n 


\ (ca cap (intersection) 


1 


\ (br box vertical rule 


c 


\ ( sb subset of 


o 


\ (ci circle 


z> 


\ ( sp superset of 


1 


\ (bv bold vertical 


C 


\ ( ib improper subset 




\ (Ic left ceiling (bracket) 


3 


\ ( ip improper superset 




\ ( re right ceiling 


e 


\ (mo member of 




\ (If left floor 





\ (es empty set 




\ (rf right floor 


oo 


\ (if infinity 




\ (It left top (brace) 


a 


\ (pd partial derivative 




\ (rt right top 


V 


\ (gr gradient 




\ (lb left bottom 


J 


\ (is integral sign 




\ ( rb right bottom 


oc 


\ (pt proportional to 




\ (Ik left center 


- 


\ (no not 




\ ( rk right center 
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24.5 Predefined general number registers 



Register 
name 


Description 


% 


Current page number. 


.b 


Emboldening factor of the current font. 


c. 


Provides general register access to the input line number in the 




current input file. Contains the same value as the read-only 




. c register. 


.R 


Number of number registers that remain available for use. 


ct 


Character type (set by width function). 


dl 


Width (maximum) of last completed diversion. 


dn 


Height (vertical size) of last completed diversion. 


dw 


Current day of the week (1 through 7). 


dy 


Current day of the month (1 through 31). 


In 


Output Une number. 


mo 


Current month (1 through 12). 


nl 


Vertical position of last printed text base line. 


sb 


Depth of string below base line (generated by width function). 


St 


Height of string above base line (generated by width function). 


yr 


Last two digits of current year. 
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24.6 Predefined read-only number registers 



Register 
name 


Description 


.$ 


Number of arguments available at the current macro level. 


$$ 


Identification number (process ID) for nrof f or troff 




processes. 


• A 


Set to 1 in the troff formatter if -a option used: always 




1 in the nrof f formatter. 


.F 


Value is a string that is the name of the current input file. 


.H 


Available horizontal resolution in basic units. 


• L 


Contains the current line spacing parameter (the value of 




the most recent . 1 s request). 


.P 


Contains the value 1 if the current page is being printed and 




is zero otherwise, that is, if the current page did not appear 




in the -0 option list. 


.T 


Set to 1 in the nrof f formatter if -T flag option used: 




always in the troff formatter. 


.V 


Available vertical resolution in basic units. 


.a 


Post-line extra line space most recently utilized using 


• C 


Number of lines read from current input file. 


.d 


Current vertical place in current diversion: equal to nl if 




no diversion. 


.f 


Current font as physical quadrant (1 through 4). 


.h 


Text base-line high-water mark on current page or 




diversion. 


-i 


Current indent. 


•J 


Indicates the current adjustment mode and type. Can be 




saved and later given to the .ad request to restore a 




previous mode. 


• k 


Contains the horizontal size of the text portion (without 




indent) of the current partially collected output line, if any. 




in the current environment. 


.1 


Current line length. 


• n 


Length of text portion on previous output line. 


.0 


Current page offset. 


•P 


Current page length. 


.s 


Current point size. 
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Register 
name 


Description 


.t 


Distance to the next trap. 


• U 


Equal to 1 in fill mode and in no-fiU mode. 


.V 


Current vertical line spacing. 


.w 


Width of previous character. 


.X 


Reserved version-dependent register. 


• y 


Reserved version-dependent register. 


. z 


Name of current diversion. 
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1. Introduction 

This chapter is a guide and reference for users of the Memorandum 
Macros. These macros provide a general-purpose package of text 
formatting macros for use with the A/UX operating system text 
formatters nrof f and trof f (refer to nrof f (1) and trof f (1) in 
A/UX Command Reference for more details). 

1.1 Document Structure 

Input for a document to be formatted with the mm text-formatting 
macro package has four major segments, any of which may be omitted. 
If present, the segments must occur in the following order: 

• The parameter-setting segment sets the general style and 
appearance of a document. The user can control page width, 
margin justification, numbering styles for headings and lists, 
page headers and footers, and many other properties of the 
document. Also, the user can add macros or redefine existing 
ones. This segment can be omitted entirely if the user is satisfied 
with default values; it produces no actual output, but performs 
only the formatter setup for the rest of the document. 

• The beginning segment includes those items that occur only 
once, at the beginning of a document; for example, title, author's 
name, and date. 

• The body segment is the actual text of the document. It may be 
as small as a single paragraph or as large as hundreds of pages. 
It may have a hierarchy of headings up to seven levels deep (see 
' 'Paragraphs and Headings' '). Headings are automatically 
numbered (if desired) and can be saved to generate the table of 
contents. Five additional levels of subordination are provided by 
a set of list macros for automatic numbering, alphabetic 
sequencing, and "marking" of list items (see "Lists"). The 
body may also contain various types of displays, tables, figures. 
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footnotes, and references (see "Displays," "Footnotes," and 
"References"). 

• The ending segment contains those items that occur only once at 
the end of a document. Included are signatures and lists of 
notations (for example, "Copy to" lists) (see "End of 
Memorandum Macros' '). Certain macros may be invoked here 
to print information that is wholly or partially derived from the 
rest of the document, such as the table of contents or the cover 
sheet for a document (see "Table of Contents and Cover 
Sheet"). 

Existence and size of these four segments varies widely among 
different document types. Although a specific item (such as date, title, 
author names) of a segment may differ depending on the document, 
there is a uniform way of typing it into an input text file. 

1.2 Input text Structure 

To make it easy to edit or revise input file text at a later time, 

• Input lines should be kept short. 

• Lines should be broken at the end of clauses. 

• Each new sentence should begin on a new line. 

1.3 Definitions 

Formatter refers to either thenrofforthetroff text-formatting 
program. 

Requests are built-in commands recognized by the formatters. 
Although a user seldom needs to use these requests directly (see "Use 
of Formatter Requests"), this chapter contains references to some of 
the requests. For example, the request 

.sp 

inserts a blank line in the output at the place the request occurs in the 
input text file. 

Macros are named collections of requests. Each macro is an 
abbreviation for a collection of requests that would otherwise require 
repetition. The inm package supplies many macros, and the user can 
define additional ones. Macros and requests share the same set of 
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names and are used in the same way. The first line of each item lists 
the name of the macro, a brief description, and a reference to the 
section in which the macro is described. The second line illustrates a 
typical macro structure. 

Strings provide character variables, each of which names a string of 
characters. Strings are often used in page headers, page footers, and 
lists. These registers share the pool of names used by requests and 
macros. A string can be given a value via the . ds (define string) 
request, and its value can be obtained by referencing its name, 
preceded by \ * (for one-character names) or \ * ( (for two-character 
names). For instance, the string dt in mm normally contains the current 
date. Thus the input line 

Today is \* (DT. 
may result in the following output: 

Today is September 15, 1988. 
The current date can be replaced, for example, 

•ds DT 01/01/85 

by invoking a macro designed for that purpose (see "Date Changes"). 
A brief description, paragraph reference, and initial (default) values are 
given for each. 

Number registers fill the role of integer variables. These registers are 
used for flags and for arithmetic and automatic numbering. A register 
can be given a value using a . nr request and be referenced by 
preceding its name by \n (for one-character names) or \n ( (for two- 
character names). For example, the following sets the value of the 
register d to one more than that of the register dd : 

.nr d l+\n{dd 

"Extending and Modifying Macro Names" contains naming 
conventions for requests, macros, strings, and number registers. 



mm Reference 4-3 



2. Usage 

This part describes how to access mm, illustrates A/UX operating 

system command lines appropriate for various output devices, and / 

describes command line flags for the mm text-formatting macro \ 

package. 

2.1 The mm command 

The mm(l) command can be used to prepare documents using the 
nrof f formatter and the Memorandum Macros. The mm command 
has options to specify preprocessing by tbl or neqn, or both, and for 
postprocessing by various output filters. 

Note: Options can occur in any order but must appear before 
the filenames. 

Any arguments or flag options that are not recognized by the mm 
command (for example, -rC3) are passed to the nrof f formatter or 
to mm, as appropriate. Options are as follows: 

Option Meaning 

-e The neqn preprocessor is to be invoked; also '^ 

causes neqn to read /usr/pub/eqnchar (see 
eqnchar(7)). 

-t The tbl(l) preprocessor is to be invoked. 

- c The c o 1 ( 1 ) postprocessor is to be invoked. 

-E The -e option of the nrof f formatter is to be 

invoked. 

-12 The 12-pitch mode is to be used. The pitch switch 

on the terminal should be set to 12 if necessary. 

- T 2 6 3 1 Output is prepared for an HP263 1 printer where 

-T2 631-e and -T2 631-C may be used for 
expanded and compressed modes, respectively 
(implies -c). 

-T 3 Output is to a DASI 300 terminal. ( 

-T300s Output is to a DASI 300S. 
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- T 3 7 Output is to a Teletype Model 37. 

-T3 82 Output is to a DTC-382. 

- T 4 a Output is to a Trendata 4000 A. 

-T450 Output is to a DASI 450. This is the default 

terminal type (unless $TERM is set; see sh(l)). It 
is also equivalent to - T 1 6 2 . 

- T 8 3 2 Output is to an Anderson Jacobson 832 terminal. 

-T 8 5 1 Output is to a C.ITOH printer. 

-Tip Output is to a device with no reverse or partial line 

motions or other special features (implies -c). 

-Ttn3 Output is to a GE terminet 300 terminal. 

-TX Output is prepared for an EBCDIC line printer. 

Any other -T option given does not produce an error; it is equivalent to 

-Tip. 

A similar command is available for use with the trof f formatter (see 
mmt(l)). 

2.2 The -cm or -mm flag 

The mm package can also be invoked by including the -mm flag as an 
argument to the formatter. The -mm flag causes the file 
/usr/lib/tmac/tmac .mto be read and processed before any 
other files. This action 

• defines the Memorandum Macros 

• sets default values for various parameters 

• initializes the formatter to be ready to process input text files 

2.3 Typical command lines 

The prototype command lines are as follows (various options are 
explained in "Parameters Set From the Command Line"): 

• Text without tables or equations: 
mm [options] filename . . . 

or 
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nroff [options] -mm filename ... 

mmt [options] filename . . . 

or 

troff [options] -mm filename ... 

Text with tables: 

mm -t [options] filename . . . 

or 

tbl filename ... I nroff [options] -mm 

mmt -t [options] filename . . . 

or 

tbl filename ... I troff [options] -mm 

Text with equations: 

mm -e [options] filename . . . 

or 

neqn /usr/pub/eqnchar _/z/enfZ/ne ... I nroff [options] -mm 

mmt -e [options] filename . . . 

or 

eqn /usr/pub/eqnchar yi/en<2me ... I troff [options] -mm 

Text with both tables and equations: 

mm -t -e [options] filename . . . 

or 

tbl filename ... I neqn /usr/pub/eqnchar\ 
I nroff [options] -mm 

mmt -t -e [options] filename . . . 
or 
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tbl filename ... I eqn /usr/pub/eqnchar\ 
I troff [options] -mm 

When formatting a document with the nrof f processor, the output 
should normally be processed for a specific type of terminal because 
the output may require some features that are specific to a given 
terminal (for example, reverse paper motion or half-line paper motion 
in both directions). Some commonly used terminal types and the 
command lines appropriate for them are given below. For more 
information, see "Parameters Set From Command Line" and 300(1), 
450(1), 4014(1), hp(l), col(l), termio(4), and term(5). 

• DASI 450 in 10-pitch, 6 lines/inch mode, with 0.75-inch offset, 
and a line length of 6 inches (60 characters) where this is the 
default terminal type so no -T option is needed (unless $term is 
set to another value): 

mm filename . . . 

or 

nroff -T450 -h -mm filename ... 

• DASI 450 in 12-pitch, 6 lines/inch mode, with 0.75-inch offset, 
and a line length of 6 inches (72 characters): 

mm -12 filename ... 

or 

nroff -T450-12 -h -mm filename ... 

or to increase the Une length to 80 characters and decrease the 
offset to 3 characters: 

mm -12 -rW80 -r03 filename ... 

or 

nroff -T450-12 -rW80 -r03 -h -ram filename ... 

• Hewlett-Packard HP264x CRT family: 

mm -Thp filename . . . 
or 
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nroff -mm filename ... I col I hp 

• Any terminal incapable of reverse paper motion and also lacking 
hardware tab stops (Texas Instruments 700 series, and so on): 

irim -T745 filename ... 

or 

nroff -mm filename ... I col -x 

The tbl(l) and eqn/neqn(l) formatters must be invoked as shown in 
the command lines illustrated earlier. 

If two-column processing is used with the nroff formatter, either the 
-c option must be specified to mm (mm uses the col program 
automatically for many terminal types) or the nroff formatter output 
must be postprocessed by col. See col(l) in AlUX Command 
Reference, "Two-Column Output" and "The mm Command." In the 
latter case, the -T37 terminal type must be specified to the nroff 
formatter, the -h option must not be specified, and the output of 
col(l) must be processed by the appropriate terminal filter (for 
example, 450(1)); mm(l) with the -c option handles all this 
automatically. 

2.4 Parameters set from command line 

Number registers are commonly used within mm to hold parameter 
values that control various aspects of output style. Many of these 
values can be changed within the text files with .nr requests. In 
addition, some of these registers can be set from the command line. 
This is a useful feature for those parameters that should not be 
permanently embedded within the input text. If used, the number 
registers (with the exception of the P register) must be set on the 
command line or before the mm macro definitions are processed. The 
number register meanings are as follows: 

-rAn n = 1, has the effect of invoking the . AF macro without 
an argument (see "Alternate First-Page Format"). 

-rCn Sets type of copy (for example, DRAFT) to be printed at 
the bottom of each page (see "Page Footer"), 
n = 1, OFFICIAL FILE COPY. 
rt = 2, DATE FILE COPY. 
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n = 3, DRAFT with single spacing and default 
paragraph style. 

n = 4, DRAFT with double spacing and 10-space 
paragraph indent. 

-rDl S&ts debug modG. This flag requests the formatter to 

continue processing even if mm detects errors that would 
otherwise cause termination. It also includes some 
debugging information in the default page header (see 
"Page Header" and "SCCS Release Identification"). 

- rErt Controls the font of Subject/Date/From fields. 

n = 0, fields are bold (default for the trof f formatter). 
« = 1, fields are roman font (regular text default for the 
nrof f formatter). 

- r lA; Sets length of physical page to k fines. 

For the nrof f formatter, A; is an unsealed number 

representing lines. 

For the trof f formatter, k must be scaled (i for 

inches, v for vertical spaces). 

Default value is 66 lines per page. 

-rNrt Specifies page numbering style. 

n = (default), all pages get the prevailing header 
n = 1, page header replaces footer on page 1 only, 
n = 2, page header is omitted from page 1. 
rt = 3, "section-page" numbering occurs ( . fd and . RP 
define footnote and reference numbering in sections). 
(See "Page Header," "First-Level Headings and Page- 
Numbering Style," "Format Style of Foomote Text" 
and "Reference Page.") 

n = 4, default page header is suppressed; however, a 
user-specified header is not affected, 
n = 5, "section-page" and "section-figure" numbering 
occurs. 



mm Reference 4-9 



It 


Page1 


Pages 2ff 





Header 


Header 


1 


Header replaces footer 


Header 


2 


No header 


Header 


3 


"Section-page" as footer 


Same as page 1 


4 


No header 


No header unless .PH defined 


5 


"Section-page" as footer 
and ' 'section-figure' ' 


Same as page 1 



Contents of the prevailing header and footer do not 
depend on number register N value; N controls only 
whether the header (N=3) or the footer (N=5) is printed, 
as well as the page-numbering style. If header and 
footer are null (see "Page Header" and "Page 
Footer"), the value ofN is irrelevant. 

- r OA; Offsets output k spaces to the right. 

For the nrof f formatter, ^ is an unsealed number 

representing character positions. 

For the t rof f formatter, k must be scaled. 

This flag is helpful for adjusting output positioning on 

some terminals. If this register is not set on the 

command line, the default offset is 0.75 inch in nrof f 

and 0.5 inch in trof f . 

Note: Register name is the capital letter o. 

- r P« Specifies that pages of the document are to be numbered 

starting with n. 

This register may also be set via a . nr request in the 

input text. 

-rSn Sets point size and vertical spacing for the document. 
The default n is 10, that is, 10-point type on 12-point 
vertical spacing, giving 6 lines per inch (see "Setting 
Point Size and Vertical Spacing"). 
This flag applies to the trof f formatter only. 

-rTn Provides register settings for certain devices. 

n = 1, line length and page offset are set to 80 and 3, 
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respectively. 

n = 2, changes the page length to 84 lines per page and 

inhibits underlining; it is meant for output sent to the 

Versatec printer. 

The default value for n is 0. 

This flag applies to the nrof f formatter only. 

- rU 1 Controls underlining of section headings. 

This flag causes only letters and digits to be underlined. 
Otherwise, all characters (including spaces) are 
underlined (see "nrof f Underlining Style"). 
This flag applies to the nrof f formatter only. 

- rV!k Sets page width (line length and title length) to k. 

For the nrof f formatter, ^ is an unsealed number 

representing character positions. 

For the t rof f formatter, k must be scaled. 

This flag can be used to change page width from the 

default value of 6 inches (60 characters in 10 pitch or 72 

characters in 12 pitch). 

2.5 Omission Of -mm flag 

If a large number of arguments is required on the command line, it may 
be convenient to set up the first (or only) input file of a document as 
follows: 

zero or more initializations of registers 
listed in ' 'Parameters Set From Command Line' ' 
.so /usr/lib/tmac/tmac .m 
remainder of text 

In this case, the user must not use the -mm flag (nor the mm(l) or 
mmt(l) command); the . so request has the equivalent effect, but 
registers shown in "Parameters Set From Command Line" must be 
initialized before the . so request because their values are meaningful 
only if set before macro definitions are processed. When using this 
method, it is best to lock into the input file only those parameters that 
are seldom changed. For example, 
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.nr W 80 

.nr O 10 

.nr N 3 

.so /usr/lib/tmac/tmac.m 

.H 1 "INTRODUCTION" 



specifies, for the nrof f formatter, a line length (w) of 80, a page offset 
(O) of 10, and section-page (N) numbering, 

3. Formatting concepts 
3.1 Basic terms 

Normal action of the formatters is to fill output lines from one or more 
input lines. Output lines may be justified so that both the left and right 
margins are aligned. As lines are being filled, words may also be 
hyphenated as necessary (see "Hyphenation"). It is possible to turn 
any of these modes on and off by using . SA (see "Justification of 
Right Margin"), Hy (see "Hyphenation") and the . nf and . f i 
formatter requests. Turning off fill mode also turns off justification and 
hyphenation. 

Certain formatting commands (requests and macros) cause filling of the 
current output line to cease, the line (of whatever length) to be printed, 
and subsequent text to begin a new output line. This printing of a 
partially filled output line is known as a break. A few formatter 
requests and most of the mm macros cause a break. 

Formatter requests can be used with mm (see "Use of Formatter 
Requests"); however, there are consequences and side effects that each 
such request might have. A good rule is to use formatter requests only 
when absolutely necessary. The mm macros described herein should be 
used in most cases because 

• It is much easier to control (and change at any later point in time) 
the overall style of the document. 

• Complicated features such as footnotes or tables of contents can 
be obtained with ease. 



4-1 2 A/UX Text Processing Tools 



• The user is insulated from the complexities of the formatter 
language. 

3.2 Arguments and double quotes 

For any macro call, a null argument is an argument whose width is 
zero. Such an argument often has a special meaning; the preferred 
form for a null argument is " ". Omitting an argument is not the same 
as supplying a null argument (for example, the . mt macro; see 
"Memorandum Types"). Omitted arguments can occur only at the 
end of an argument list; null arguments can occur anywhere in the list. 

Any macro argument containing ordinary (paddable) spaces must be 
enclosed in double quotes. A double quote (") is a single character 
which should not be confused with two close quotes (' or open 
quotes C* ^). Unless you enclose an argument containing spaces in 
double quotes, it will be treated as several separate arguments. 

Double quotes are not permitted as part of the value of a macro 
argument or of a string that is to be used as a macro argument. If it is 
necessary to have a macro argument value, two close quotes C ')ot 
open quotes ( ■* ^) or a combination of the two may be used instead. 
This restriction is necessary because many macro arguments are 
processed (interpreted) a variable number of times. For example, 
headings are first printed in the text and may be reprinted in the table of 
contents. 

3.3 Unpaddable spaces 

When output lines are justified to give an even right margin, existing 
spaces in a line may have additional spaces appended to them. This 
may distort the desired alignment of text. To avoid this distortion, it is 
necessary to specify a space that cannot be expanded during 
justification, that is, an unpaddable space. There are several ways to 
accompUsh this: 

• Type a backslash followed by a space. This pair of characters 
directly generates an unpaddable space. 

• Sacrifice some seldom-used character to be translated into a 
space when output is generated. 

Because this translation occurs after justification, the chosen character 
may be used anywhere an unpaddable space is desired. The tilde (~) is 
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often used with the translation macro for this purpose. To use the tilde 
in this way, the following is inserted at the beginning of the document: 



.tr ~ 

If a tilde must actually appear in the output, it can be temporarily 
"recovered" by inserting 

.tr — 

before the place where needed. Its previous usage is restored by 
repeating the . t r ~ after a break or after the Une containing the tilde 
has been forced out. 

Note: Use of the tilde in this fashion is not recommended for 
documents in which the tilde is used within equations. 

3.4 Hyphenation 

Formatters do not perform hyphenation unless it is requested. 
Hyphenation can be turned on in the body of the text by specifying 

.nr Hy 1 

once at the beginning of the document input file. "Format Style of 
Footnote Text" describes hyphenation within footnotes and across 
pages. 

If hyphenation is requested, formatters will automatically hyphenate 
words if need be. However, the user may specify hyphenation points 
for a specific occurrence of any word with a special character known as 
a hyphenation indicator or may specify hyphenation points for a small 
list of words (about 128 characters). 

If the hyphenation indicator (initially, the two-character sequence \%) 
appears at the beginning of a word, the word is not hyphenated. 
Alternatively, this sequence can be used to indicate legal hyphenation 
points inside a word. All occurrences of the hyphenation indicator 
disappear when output is generated. 

The user may specify a different hyphenation indicator. 

. HC [hyphenation-indicator] 
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The circumflex (") is often used for this purpose by inserting the 
following at the beginning of a document input text file: 



,HC 



Note: Any word or phrase containing hyphens or dashes (also 
known as em dashes) will be hyphenated immediately after a 
hyphen or dash if it is necessary to hyphenate, even if the 
formatter hyphenation function is turned off. 

The user may supply, via the exception word . hw request, a small list 
of words with the proper hyphenation points indicated. For example, to 
indicate the proper hyphenation of the word "printout," the user may 
specify 

.hw print-out 

3.5 Tabs 

Macros .MT (see "Memorandum Types"), . TC (see "Table of 
Contents"), and . CS (see "Cover Sheet") use the formatter . ta (tab) 
request to set tab stops and then restore the default values of tab 
settings (every eight characters in the nrof f formatter; every V2 inch 
in the trof f formatter). Setting tabs to other than the default values 
is the user's responsibility. 

Default tab setting values for nrof f are 9, 17, 25, ... , 161 for a total 
of 20 tab stops. Values may be separated by commas, spaces, or any 
other non-numeric character. A user may set tab stops at any value 
desired. For example, 

.ta 1.5i 3i 4 . 5i 

A tab character is interpreted with respect to its position on the input 
line rather than its position on the output Une. In general, tab 
characters should appear only on lines processed in no-fill ( . nf ) mode 
(see "Basic Terms"). 

The tbl(l) program (see "Tables") changes tab stops but does not 
restore default tab settings. 
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3.6 BEL character 

The nonprinting character BEL is used as a delimiter in many macros 
to compute the width of an argument or to delimit arbitrary text, for 
example, in page headers and footers, headings, and lists. Users who 
include BEL characters in their input text file (especially in arguments 
to macros) wiU receive mangled output. See "Page Headers and 
Footers," "Paragraphs and Headings," and "Lists." 

3.7 Bullets 

A bullet ( •) is often obtained on a typewriter terminal by using an "o" 
overstruck by a "+". For compatibility with the trof f formatter, a 
bullet string is provided by mm with the following sequence: 

\* (BU 

The bullet list ( . BL) macro uses this string to generate automatically 
the bullets for buUet-listed items (see "Bullet List"). 

3.8 Dashes, minus signs, and hyphens 

The trof f formatter has distinct graphics for a dash, a minus sign, 
and a hyphen; the nrof f formatter does not. 

• Users who intend to use the nrof f formatter only may use the 
minus sign (-) for the minus, hyphen, and dash. 

• Users who plan to use the t rof f formatter primarily should 
follow trof f escape conventions (that is, \ (mi for minus, 
\ ( em for dash, and \ ( hy for hyphen). 

• Users who plan to use both formatters must take care during 
input text file preparation. Unfortunately, these graphic 
characters cannot be represented in a way that is both compatible 
and convenient for both formatters. 

The following approach is suggested: 

Dash Type \ * ( EM for each text dash for both n r o f f and 

trof f formatters. This string generates an em dash 
( — ) in the trof f formatter and two hyphens (— ) in 
the nrof f formatter. Dash list ( . DL) macros (see 
"Dash List") automatically generate the em dash 
for each list item. 
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Hyphen Type - and use as is for both formatters. The 
nrof f formatter will print it as is. The t rof f 
formatter will print a true hyphen. 

Minus Type \ - for a true minus sign regardless of 

formatter. The nrof f formatter will ignore the \. 
The trof f formatter will print a true minus sign 

3.9 Trademark String 

A trademark string \ * ( Tm is available with rrim. This places the letters 
"TM' ' one-half line above the text that it follows. For example, 

The 

A/UX\* (Tm manual 

is available from the library. 

yields 

The AAXX™ manual 

is available from the library. 

3.1 Use of formatter requests 

Most formatter requests should not be used with mm because mm 
provides the corresponding formatting functions in a much more user- 
oriented and surprise-free fashion than do the basic formatter requests. 
However, some formatter requests are useful with mm, namely the 
following: 



.af 


Assign format 


.br 


Break 


.ce 


Center 


• de 


Define macro 


.ds 


Define string 


• fi 


Fill output lines 


• hw 


Hyphen word exceptions 


.Is 


Line spacing 


.nf 


No filling of output lines 


.nr 


Number register define and set 


.nx 


Next file (does not return) 


. rm 


Remove macro 


. rr 


Remove register 
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.rs 


Restore spacing 


.so 


Source file and return 


.sp 


Space 


.ta 


Tab stop settings 


.ti 


Temporary indent 


.tl 


Tide 


.tr 


Translate 


1 


Escape 



The . f p (font position), . Ig (ligature mode), and . ss (space- 
character size) requests are also sometimes useful for the trof f 
formatter. Use of other requests without fully understanding their 
implications very often leads to disaster. 

4. Paragraphs and headings 
4.1 Paragraphs 

.P [type] 

one or more lines of text 

The . P macro is used to control paragraph style. \ 

4.1.1 Paragraph indentation 

An indented or an unindented paragraph is defined with the type 
argument 

Left justified 

1 Indented 

In a left-justified paragraph, the first fine begins at the left margin. In 
an indented paragraph, the paragraph is indented the amount specified 
in the Pi register (default value is 5 ens). For example, to indent 
paragraphs by ten spaces in nrof f the following is entered at the 
beginning of the document input file: 

.nr Pi 10 

A document input file possesses a default paragraph type obtained by 

specifying . p before each paragraph that does not follow a heading . 

(see ' 'Numbered Headings")- Default paragraph type is controlled by ^ 

the Pt number register. 
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• The initial value of Pt is 0, which provides left-justified 
paragraphs. 

• All paragraphs can be forced to be indented by inserting the 
following at the beginning of the document input file: 

.nr Pt 1 

• All paragraphs can be indented (except when they occur after 
headings, lists, and displays) by entering the following at the 
beginning of the document input file: 

•nr Pt 2 

Both the Pi and Pt register values must be greater than zero for any 
paragraphs to be indented. 

Note: Values that specify indentation must be unsealed and are 
treated as character positions, that is, as a number of ens. In the 
nrof f formatter, an en is equal to the width of a character. In 
the t rof f formatter, an en is the number of points (1 point = 
1/72 of an inch) equal to half the current point size. 

Regardless of the value of Pt, an individual paragraph can be forced to 
be left-justified or indented. The . P macro request forces left 
justification; . P 1 causes indentation by the amount specified by the 
register Pi. 

If . P occurs inside a list, the indent (if any) of the paragraph is added 
to the current list indent (see ' 'Lists' '). 

4.1.2 Numbered paragraphs 

Numbered paragraphs may be produced by setting the Np register to 1. 
This produces paragraphs numbered within first-level headings, for 
example, 1.01, 1.02, 1.03, 2.01, and so forth. 

A different style of numbered paragraphs is obtained by using the . nP 
macro rather than the . P macro for paragraphs. This produces 
paragraphs that are numbered within second-level headings. 
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•H 1 "FIRST HEADING" 

.H 2 "Second Heading" 

.nP 

one or more lines of text 

The paragraphs contain a double-line indent in which the text of the 
second Une is indented to be aligned with the text of the first line so 
that the number stands out. 

4.1.3 Spacing between paragraphs 

The Ps number register controls the amount of spacing between 
paragraphs. By default, Ps is set to 1, yielding one blank space in 
nrof f , one-half a vertical space in trof f . 

4.2 Numbered headings 

.H level [heading-text] [heading-suffix] 
zero or more lines of text 

The level argument provides the numbered heading level. There are 
seven heading levels; level 1 is the highest, level 7 is the lowest. 

The heading-text argument is the text of the heading. If the heading 
contains more than one word or contains spaces, the entire argument 
must be enclosed in double quotes. 

The heading-suffix argument may be used for foomote marks which 
should not appear with heading text in the table of contents. 

There is no need for a . P macro immediately after a . H or . HU (see 
"Unnumbered Headings") because the . H macro also performs the 
function of the . P macro. Any immediately following . P macro is 
ignored. It is, however, good practice to start every paragraph with a 
. P macro, thereby ensuring that all paragraphs begin with a . P 
throughout a document. 

4.2.1 Default headings 

The effect of the . H macro varies according to the level argument. 
First-level headings are preceded by two blank lines in nrof f and one 
vertical space in trof f; all other levels are preceded by one blank line 
in nrof f and one-half a vertical space in t rof f . The following 
describes the default effect of the level argument. 
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. H 1 heading-text 

Produces an underlined (italicized) font heading, followed by a 
single blank line. The text that follows begins on a new line and 
is indented according to the current paragraph type. Full capital 
letters can be used to make the heading stand out. 

. H n heading-text 

Produces an underlined (italicized) font heading followed by two 
spaces (3 < « < 7). The following text begins on the same line, 
that is, these are run-in headings. 

Appropriate numbering and spacing (horizontal and vertical) occurs 
even if the heading-text argument is omitted from a . H macro call. 

Note: Users satisfied with the default appearance of headings 
may skip to the section entitled "Unnumbered Headings." 

4.2.2 Altering appearance 

The user can modify the appearance of headings quite easily by setting 
certain registers and strings at the beginning of the document input text 
file. This permits quick alteration of a document's style because this 
style-control information is concentrated in a few lines rather than 
being distributed throughout the document. 

4.2.2.1 Prespacing and page ejection 

A first-level heading ( . H 1) normally has two blank lines (one vertical 
space) preceding it, and all other headings are preceded by one blank 
line (nrof f ) or one-half a vertical space (trof f ). If a multiUne 
heading were to be split across pages, it is automatically moved to the 
top of the next page. Every first-level heading may be forced to the top 
of a new page by inserting 

.nr Ej 1 

at the beginning of the document input text file. Long documents may 
be made more manageable if each section starts on a new page. Setting 
the E j (eject) register to a higher value causes the same effect for 
headings up to that level, that is, a page eject occurs if the heading level 
is less than or equal to the E j value. 
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4.2.2.2 Spacing after headings 

Three registers control the appearance of text immediately following a 
. H call. The registers are Hb (heading break level), Hs (heading space 



level), and Hi (post-heading indent). \^ 

If the heading level is less than or equal to the value of Hb, a break (see 
"Basic Terms") occurs after the heading. 

If the heading level is less than or equal to the value of Hs, a blank hne 
(nrof f ) or one-half a vertical space (trof f ) is inserted after the 
heading. 

If a heading level is greater than the value of Hb and also greater than 
the value of Hs, then the heading (if any) is run into the following text. 
These registers permit headings to be separated from the text in a 
consistent way throughout a document while allowing easy alteration 
of white space and heading emphasis. The default value for Hb and Hs 
is 2. 

For any stand-alone heading, that is, a heading not run into the 
following text, alignment of the next line of output is controlled by the 
Hi number register. 

• If Hi is 0, text is left-justified. 

• If Hi is 1 (the default value), text is indented according to the 
paragraph type as specified by the Pt register (see "Paragraph 
Indentation"). 

• If Hi is 2, text is indented to line up with the first word of the 
heading itself so that the heading number stands out more 
clearly. 

To cause a blank line (nrof f) or one-half a vertical space (t rof f ) to 
appear after the first three heading levels, to have no run-in headings, 
and to force the text following all headings to be left-justified 
(regardless of the value of Pt), the following should appear at the 
beginning of the document input text file: 

.nr Hs 3 

.nr Hb 7 ( 

.nr Hi 
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4.2.2.3 Centered headings 

The He register can be used to obtain centered headings. A heading is 
centered if its level argument is less than or equal to He and if it is also 
a stand-alone heading. The He register is initially (no centered 
headings). 

4.2.2.4 Bold, italic, and underlined headings 

4.2.2.4.1 Control by level 

Any heading that is underlined by the nrof f formatter is italicized by 
the troff formatter. The string HF (heading font) contains seven 
codes that specify fonts for heading levels 1 through 7. You can use 
any font number defined on your output device, for example; 



Formatter 


HF Code 


Default 
HF Code 


1 2 


3 


nrof f 
troff 


no underline underline 
roman italic 


bold 
bold 


2 2 2 2 2 2 2 
2 2 2 2 2 2 2 



Thus, levels 1 through 7 are underlined by the nrof f formatter and 
italicized by the troff formatter. The user may reset HF as desired. 
Any value omitted from the right end of the list is assumed to be a 1. 
The following request would result in levels 1 through 5 in bold font 
and levels 6 and 7 in roman font: 

.ds HF 3 3 3 3 3 

4.2.2.4.2 nroff underlining style 

The nroff formatter underlines in either of two styles: 

• The normal style ( . ul request) is used to underline only letters 
and digits. 

• The continuous style ( . cu request) underlines all characters 
including spaces. 

By default, inm attempts to use the continuous style on any heading that 
is to be underlined and is short enough to fit on a single line. If a 
heading is to be underlined but is longer than a single line, the heading 
is underlined in the normal style (only letters and digits). 
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All underlining of headings can be forced to the normal style by using 
the -rUl flag option when invoking the nrof f formatter (see 
"Parameters Set From Command Line")- 

4.2.2.4.3 Heading point sizes 

The user can specify the desired point size for each heading level with 
the HP string (for use with the trof f formatter only). 

.ds HP [psl] {ps2] [ps3] {ps4] [ps5] [ps6] \ps7] 

By default, the text of headings ( . H and . HU) is printed in the same 
point size as the body except that bold stand-alone headings are printed 
in a size one point smaller than the body. The string HP, similar to the 
string HF, can be specified to contain up to seven values, corresponding 
to the seven levels of headings. For example, 

.ds HP 12 12 10 10 10 10 10 

specifies that the first- and second-level headings are to be printed in 
12-point type with the remainder printed in 10-point. Specified values 
may also be relative point-size changes, for example, 

.ds HP +2 +2 -1 -1 

If absolute point sizes are specified, then absolute sizes will be used 
regardless of the point size of the body of the document. If relative 
point sizes are specified, then point sizes for headings will be relative to 
the point size of the body even if the latter is changed. 

Null or zero values imply that default size will be used for the 
corresponding heading level. 

Note: Only the point size of the headings is affected. 
Specifying a large point size without providing increased 
vertical spacing (via .HXor . HZ) may cause overprinting. 



4.2.2.5 Marking styles— numerals and concatenation 

The registers named HI through H7 are used as counters for the seven 
levels of headings. Register values are normally printed using Arabic 
numerals. The . hm macro (heading mark style) allows this choice to 
be overridden, thus providing oufline and other document styles. 
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.HM [argl] ... [argT] 

This macro can have up to seven arguments; each argument is a string 
indicating the type of marking to be used. Legal arguments and their 
meanings are 



Argument 


Meaning 


1 


Arabic (default for all levels) 


0001 


Arabic with enough leading zeros 




to get the specified number of digits 


A 


Uppercase alphabetic 


a 


Lowercase alphabetic 


I 


Uppercase roman 


i 


Lowercase roman 


omitted 


Interpreted as 1 (arable) 


illegal 


No effect 



By default, the complete heading mark for a given level is built by 
concatenating the mark for that level to the right of aU marks for all 
levels of higher value. To inhibit the concatenation of heading level 
marks, that is, to obtain just the current level mark followed by a 
period, the heading mark type register (Ht) is set to 1. For example, 
input for a commonly used outline style is 

.HM I A 1 a i 
.nr Ht 1 

4.3 Unnumbered headings 

The . HU macro is a special case of . h; it is handled in the same way as 
. H except that no heading mark is printed. 

.HU heading-text 

In order to preserve the hierarchical structure of headings when . h and 
. HU calls are intermixed, each . HU heading is considered to exist at 
the level given by register Hu, whose initial value is 2. Thus, in the 
normal case, the only difference between 

.HU heading-text 

and 
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.H 2 heading-text 

is the printing of the heading mark for the latter. Both macros have the 
effect of incrementing the numbering counter for level 2 and resetting 
to zero the counters for levels 3 through 7. Typically, the value of Hu 
should be set to make unnumbered headings (if any) be the lowest- 
level headings in a document. 

The . HU macro can be especially helpful in setting up appendixes and 
other sections that may not fit well into the numbering scheme of the 
main body of a document (see "Appendix Headings"). 

4.4 Headings and table of contents 

The text of headings and their corresponding page numbers can be 
collected automatically for a table of contents. This is accomplished by 
doing the following: 

• specifying in the contents level register, CI, what level headings 
are to be saved 

• invoking the . TC macro (see "Table of Contents") at the end of 
the document. 

Any heading whose level is less than or equal to the value of the CI 
register is saved and later displayed in the table of contents. The 
default value for the CI register is 2, that is, the first two levels of 
headings are saved. 

Due to the way headings are saved, it is possible to exceed the 
formatter's storage capacity, particularly when saving many levels of 
many headings, while also processing displays (see "Displays") and 
footnotes (see "Footnotes"). If this happens, the "Out of temp file 
space" formatter error message will be issued; the only remedy is to 
save fewer levels, to have fewer words in the heading text or do both. 

4.5 First-level iieadings and page-numbering style 

By default, pages are numbered sequentially at the top of the page. For 
large documents, it may be desirable to use page numbering of the 
section-page form where section is the number of the current first-level 
heading. This page numbering style can be achieved by specifying the 
-rN3 or -rN5 flag option on the command line (see "Default Header 
and Footer with Section-Page Numbering"). This also has the effect of 
setting E j to 1, which causes each first-level section to begin on a new 
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page. In this style, the page number is printed at the bottom of the page 
so that the correct section number is printed. 

4.6 User exit macros 

Note: This section is intended primarily for users who are 
accustomed to writing formatter macros. 

.HX dlevel rlevel heading-text 
• HY dlevel rlevel heading-text 
.HZ dlevel rlevel heading-text 

The . HX, . HY, and . HZ macros are the means by which the user 
obtains a final level of control over the previously described heading 
mechanism. These macros are not defined by mm, they are intended to 
be defined by the user. The . H macro call invokes . HX shortly before 
the actual heading text is printed; it calls . HZ as its last action. After 
. HX is invoked, the size of the heading is calculated. This processing 
causes certain features that may have been included in . HX, such as 
. ti for temporary indent, to be lost. After the size calculation, . HY is 
invoked so that the user may specify these features again. All default 
actions occur if these macros are not defined. If . HX, . HY, or . HZ are 
defined by the user, user-supplied definition is interpreted at the 
appropriate point. These macros can influence handhng of all headings 
because the , HU macro is actually a special case of the . H macro. 

If the user first invokes the . H macro, then the derived level argument 
{dlevel) and the real level argument {rlevel) both are equal to the level 
given in the . H invocation. If the user first invokes the . HU macro (see 
"Unnumbered Headings"), dlevel is equal to the contents of register 
Hu, and rlevel is 0. In both cases, heading-text is the text of the 
original invocation. 

By the time . H calls . HX, it has already incremented the heading 
counter of the specified level, produced blank fines (vertical spaces) to 
precede the heading (see "Prespacing and Page Ejection"), and 
accumulated the "heading mark", that is, the string of digits, letters, 
and periods needed for a numbered heading. When . HX is called, all 
user-accessible registers and strings can be referenced, as well as the 
following: 
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siring } If rlevel is nonzero, this string contains the heading 
mark. Two unpaddable spaces (to separate the mark 
from the heading) have been appended to this string. 
If rlevel is 0, this string is null. 

register ; This register indicates the type of spacing that is to 
follow the heading (see "Spacing after Headings"). 
A value of means that the heading is run-in. 
A value of 1 means a break (but no blank Une) is to 
follow the heading. 

A value of 2 means that a blank line (nrof f ) or 
one-half a vertical space (trof f ) is to follow the 
heading. 

string } 2 If register ; is 0, this string contains two 

unpaddable spaces that will be used to separate the 
(run-in) heading from the following text. 
If register ; is nonzero, this string is null. 

register ; 3 This register contains an adjustment factor for a . ne 
request issued before the heading is actually printed. 
On entry to . HX, it has the value 3 if dlevel equals 1, 
and a value of 1 otherwise. The . ne request is for 
the following number of Unes: the contents of the 
register ; taken as blank lines (nrof f) or halves 
of vertical space (t rof f ) plus the contents of 
register ; 3 as blank lines (nrof f ) or halves of 
vertical space (trof f) plus the number of lines of 
the heading. 

The user may alter the values of } 0, } 2, and ; 3 within . HX. The 
following are examples of actions that might be performed by defining 
. HX to include the lines shown: 

• Change first-level heading mark from format n. to n.O: 

.if \\$1=1 .ds }0 \\n(H1.0\<sp>\<sp> 
(where <sp> stands for a space) 

• Separate run-in heading from the text with a period and two 
unpaddable spaces: 



4-28 



A/UX Text Processing Tools 



• if \\n{;0=0 .ds }2 .\<Sp>\<Sp> 

• Assure that at least 15 lines are left on the page before printing a 
first-level heading: 

•if \\$1=1 .nr ;3 (15-\\n(;0)v 

• Add three additional blank lines before each first-level heading: 

•if \\$1=1 .sp 3 

• Indent level 3 run-in headings by five spaces: 

.if \\$1=3 -ti 5n 

If temporary strings or macros are used within . HX, their names should 
be chosen with care (see "Naming Conventions"). 

When the . HY macro is called after the . ne is issued, certain features 
requested in , HX must be repeated. For example, 

• de HY 

.if \\$1=3 .ti 5n 

The . HZ macro is called at the end of . H to permit user-controlled 
actions after the heading is produced. In a large document, sections 
may correspond to chapters of a book; and the user may want to change 
a page header or footer, for example, 

.de HZ 

.if \\$1=1 .PF "Section \\$3" 

4.7 Hints for large documents 

A large document is often organized for convenience into one input 
text file per section. If the files are numbered, it is wise to use enough 
digits in the names of these files for the maximum number of sections, 
that is, use suffix numbers 01 through 20 rather than 1 through 9 and 10 
through 20. 

Users often want to format individual sections of long documents. To 
do this with the correct section numbers, it is necessary to set register 
HI to one less than the number of the section just before the 
corresponding . H 1 call. For example, at the beginning of Part 5, 
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insert 

.nr HI 4 



It will also be necessary to set the correct page number by using the 
, pn request or the -rPn flag option. 

Note: This is not good practice. It defeats the automatic 
(re)numbering of sections when sections are added or deleted. 
Such lines should be removed as soon as possible. 



5. Lists 

This part describes different styles of lists; automatically numbered and 
alphabetized lists, bullet Usts, dash lists, lists with arbitrary marks, and 
lists starting with arbitrary strings, that is, with terms or phrases to be 
defined. 

5.1 List spacing 

Spacing at the beginning of the list and between items can be 
suppressed by setting the hst space register (ls). The Ls register is set 
to the innermost list level for which spacing is done. For example, 

.nr Ls 

specifies that no spacing will occur around any list items. The default 
value for Ls is six (which is the maximum Ust-nesting level). 

5.2 List macros 

In order to avoid repetitive typing of arguments to describe the style or 
appearance of items in a list, mm provides a convenient way to specify 
lists. All lists share the same overall structure and are composed of the 
following basic parts: 

• A list-initialization macro (. AL .BL, ,DL, .ML, .RL, or .VL) 
determines the style of the list: line spacing, indentation, 
marking with special symbols, and numbering or alphabetizing 
of list items. 

• One or more list-item macros ( . LI) identify unique items to the 
system. They are followed by the actual text of the 
corresponding hst items. 



4-30 A/UX Text Processing Tools 



• The list-end macro ( . le) identifies the end of the list. It 
terminates the list and restores the previous indentation. 

Lists may be nested up to six levels. The list-initialization macro saves 
the previous list status (indentation, marking, style, and so forth); the 
. LE macro restores it. 

With this approach, the format of a list is specified only once at the 
beginning of the list. In addition, by building onto the existing 
structure, users may create their own customized sets of list macros 
with relatively little effort (see "List-Begin Macro and Customized 
Lists" and "User-Defined List Structures"). 

5.2.1 List-initialization macros 

List-initialization macros are implemented as calls to the more basic 
. LB macro (see "List-Begin Macro and Customized Lists"). They are 

. AL Automatically Numbered or Alphabetized List 
.BL Bullet List 

• DL Dash List 

. ML Marked List 
. RL Reference List 
. VL Variable-Item List 

5.3 Automatically numbered or alpliabetized list 

The . AL macro is used to begin sequentially numbered or alphabetized 
lists. 

.AL [type] [text-indent] [1] 

If there are no arguments, the list is numbered; and text is indented by 
Li (default is six) spaces from the indent in force when the . AL is 
called. This leaves room for a space, two digits, a period, and two 
spaces before the text. Values that specify indentation must be 
unsealed and are treated as character positions, that is, number of ens. 
The string . AL A 5 is used to initialize the following list: 

A. The type argument may be given to obtain a different type of 
sequencing. Its value indicates the first element in the sequence 
desired. If type argument is omitted or null, the value 1 is 
assumed. Listed below are the arguments and interpretations: 
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Argument Interpretation 

1 Arabic (default for all levels) 

A Uppercase alphabetic 

a Lowercase alphabetic 

I Uppercase roman 

i IvOwercase roman 

B . If text-indent argument is non-null, it is used as the number of 
spaces from the current indent to the text, that is, it is used 
instead of the Li register for this list only. If text-indent 
argument is null, the value of Li will be used. 

C. If the third argument is given, a blank line (nrof f ) or one-half a 
vertical space (trof f ) will not separate items in the list. A 
blank line will occur before the first item however. 

5.4 Bullet list 

The . BL macro begins a bullet list. 

.BL [text-indent] [1] 

Each list item is marked by a bullet ( •) followed by one space. The 
string . BL 5 is used to initialize the following list: 

• If the text-indent argument is specified (non-null), it overrides the 
default indentation which is the amount of paragraph indentation 
as given in the Pi register (see "Paragraphs"). In the default 
case, the text of a bullet list lines up with the first line of indented 
paragraphs. 

• If the second argument is specified, no blank lines will separate 
items in the fist. 

5.5 Dash list 

The . DL macro begins a dash list. 

.DL [text-indent] [1] 

Each list item is marked by a dash ( — ) followed by one space. The 
string . DL 5 is used to initialize the following list: 

— If the text-indent argument is specified (non-null), it overrides the 
default indentation which is the amount of paragraph indentation 
as given in the Pi register (see "Paragraphs"). In the default 
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case, the text of a dash list lines up with the first line of indented 
paragraphs. 

— If the second argument is specified, no blank lines will separate 
items in the list. 

5.6 Marked list 

The . ML macro is much like . BL and . DL macros but expects the user 
to specify an arbitrary mark which may consist of more than a single 
character. 

.ML mark [text-indent] [1] 

The string .ML \ ( sq 5 is used to initialize the following list: 

n Text is indented text-indent spaces if the second argument is 
specified (non-null); otherwise, the text is indented one more 
space than the width of mark. 

n If the third argument is specified, no blank lines will separate 
items in the list. 

Note: The mark must not contain ordinary (paddable) spaces 
because alignment of items will be lost if the right margin is 
justified (see "Unpaddable Spaces"). 

5.7 Reference list 

A . RL macro call begins an automatically numbered list in which the 
numbers are enclosed by square brackets ( [ ] ). 

.RL [text-indent] [1] 

The string , RL 5 is used to initialize the following list: 

[1] If text-indent argument is specified (non-null), it is used as the 
number of spaces from the current indent to the text, that is, it is 
used instead of Li for this list only. If text-indent argument is 
omitted or null, the value of Li is used. 

[2] If the second argument is specified, no blank lines will separate 
the items in the list. 
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5.8 Variable-item list 

When a list begins with a , VL macro, there is effectively no current 
mark; it is expected that each . LI will provide its own mark. 

.VL text-indent [mark-indent] [1] 

This form is typically used to display definitions of terms or phrases. 

• text-indent provides the distance from current indent to 
beginning of the text. 

• mark indent produces the number of spaces from current indent 
to beginning of the mark, and it defaults to if omitted or null. 

• If the third argument is specified, no blank lines will separate 
items in the fist. 

An example of . VL macro usage is shown below: 

.VL 20 5 

•LI "First\ Mark" 

This is the first mark specified for this list, 

.LI "SecondX Mark" 

.br 

This is the second mark specified for this list. 

The .br request causes a break so that this 

text will appear one line below the mark. 

.LI "ThirdX Mark\ LongerX Than\ Indent:" 

This item shows the effect of a long mark; 

one space separates the mark from the text. 

.LI "\ " 

This item has a nonprinting mark and effectively 

produces a list item that is indented. 

.LI 

This item has an omitted mark 

and produces a ^ ^hanging indent.'' 

The first line of text is at the left margin and 

the second is indented. 

.LE 

when formatted, it yields 
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First Mark This is the first mark specified for this list. 

Second Mark 

This is the second mark specified for this list. 
The . br request causes a break so that this 
text appears one line below the mark. 

Third Mark Longer Than Indent: This item shows the effect of a 
long mark; one space separates the mark from 
the text. 

This item has a nonprinting mark (an 
unpaddable space) and effectively produces a 
Ust item that is indented. 

This item has an omitted mark and produces a "hanging indent." 
The first line of text is at the left margin and 
the second is indented. 

Note: The mark must not contain ordinary (paddable) spaces 
because alignment of items will be lost if the right margin is 
justified (see "Unpaddable Spaces"). If you do not escape the 
spaces within the double quotes containing the list item, the first 
line of the text will be slightly adjusted for the paddable spaces 
and will not Une up with the rest of the text blocks in your list, 

5.9 List-item macro 

The . LI macro is used with all Usts and for each list item. 

• LI [mark] [1] 

one or more lines of text that make up the list item 

It normally causes output of a single blank line (nrof f ) or one-half a 
vertical space (t rof f ) before its list item although this may be 
suppressed. 

• If no arguments are given, . LI labels the item with the current 
mark (except in . VL lists) which is specified by the most recent 
list-initialization macro. 

• If a single argument is given, that argument is output instead of 
the current mark. 
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• If two arguments are given, the first argument becomes a prefix 
to the current mark thus allowing the user to emphasize one or 

more items in a list. One unpaddable space is inserted between (^ 

the prefix and the mark. 

For example, 

.BL 5 

.LI 

This is a simple bullet item. 

.LI + 

This replaces the bullet with a ^ ^plus . ' ' 

.LI + 1 

This uses a ^ ^plus*" ' as prefix to the bullet. 

.LE 

when formatted yields 

• This is a simple bullet item. 

+ This replaces the bullet with a ' 'plus.' ' ^ 

+ • This uses a "plus" as prefix to the bullet. ^ 

Note: The mark must not contain ordinary (paddable) spaces 
because alignment of items will be lost if the right margin is 
justified (see "Unpaddable Spaces"). 

If the current mark (in the current list) is a null string and the first 
argument of . LI is omitted or null, the result is that of a "hanging 
indent," that is, the first line of the following text is moved to the left 
starting at the same place where mark would have started (see 
"Variable-Item List"). 

5.10 List-end macro 

The . LE macro restores the state of the list to that existing just before 
the most recent list-initialization macro call. 

.LE [1] ( 

If the optional argument is given, the . LE generates a blank line 
(nrof f ) or one-half a vertical space (t rof f ). This option should 
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generally be used only when the . le is followed by running text but 
not when followed by a macro that produces blank lines of its own, 
such as the . P or . H macro. 

The . H and . HU macros automatically clear all list information. The 
user may omit the . LE macros that would normally occur just before 
either of these macros and not receive the "le : mismatched" error 
message. Such a practice is not recommended because errors will 
occur if the list text is separated from the heading at some later time 
(for example, by insertion of text). 

5.1 1 Example of nested lists 

An example of input for the several lists and the corresponding output 
is shown below. The . AL and . DL macro calls (see "Automatically 
Numbered or Alphabetized List," and "Dash List") contained therein 
are examples of list-initialization macros. Input text is 

.AL A 5 

.LI 

This is automatically alphabetized list item A. 

This list item has an indentation of 5 ens. 

.AL 

.LI 

This is automatically numbered list item 1. 

This list item also has an indentation of 5 ens. 

.DL 

• LI 

This is a dash list item. 

.LI + 1 

This is another dash item in the same list 

as the above item with a '^plus'' as prefix. 

This is the last item in the dash list. 

.LE 

.LI 

This is item 2 in the automatically numbered list. 

This is the last item in the automatically 

numbered list. 

• LE 
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• LI 

This is item B in the automatically alphabetized list. 

This is the last item in the automatically 

numbered list. 

.LE 

The output is 

A. This is automatically alphabetized list item A. This list item has 
an indentation of 5 ens. 

1. This is automatically numbered Ust item 1. This list item 
also has an indentation of 5 ens. 

— This is a dash list item. 

+ — This is another dash item in the same list as the above item 
with a ' 'plus' ' as prefix. This is the last item in the dash 
list. 

2. This is item 2 in the automatically numbered list. This is 
the last item in the automatically numbered hst. 

B. This is item B in the automatically alphabetized list. This is the 
last item in the automatically numbered list. 

5.12 List-begin macro and customized iists 

List-initialization macros described above suffice for almost all cases. 
However, if necessary, the user may obtain more control over the 
layout of lists by using the basic list-begin macro ( . LB). 

. LB text-indent mark-indent pad type [mark] [Ll-space] [LB-space] 

The . LB macro is used by the other list-initialization macros. Its 
arguments are as follows: 

• The text-indent argument provides the number of spaces that text 
is to be indented from the current indent. Normally, this value is 
taken from the Li register (for automatic lists) or from the Pi 
register (for bullet and dash lists). 

• The combination of mark-indent and pad arguments determines 
the placement of the mark. The mark is placed within an area 
(called mark area) that starts mark-indent spaces to the right of 
the current indent and ends where the text begins (that is, ends 
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text-indent spaces to the right of the current indent). The mark- 
indent argument is typically 0. 

Within the mark area, the mark is left justified if ih&pad 
argument is 0. If pad is a number n (greater than 0) then n 
blanks are appended to the mark; the mark-indent value is 
ignored. The resulting string immediately precedes the text. The 
mark is effectively right-justified /?a(i spaces immediately to the 
left of the text. 

Arguments type and mark interact to control the type of marking 
used. If type is 0, simple marking is performed using the mark 
character or characters found in the mark argument. If type is 
greater than 0, automatic numbering or alphabetizing is done. 
Then, mark is interpreted as the first item in the sequence to be 
used for numbering or alphabetizing and is chosen from the set 
(1, A, a, I, i) as in "Automatically Numbered or Alphabetized 
List." This is summarized in the following table: 



Argument 
type mark 


Result 






>0 

>0 


Omitted 
String 
Omitted 
One of: 
l,A,a,I,i 


Hanging indent 
String is the mark 
Arabic numbering 
Automatic numbering or 
alphabetic sequencing 



Each nonzero value of type from one to six selects a different way of 
displaying the marks. The following table shows the output appearance 
for each value of type : 



Valu( 


i Appearance 


1 


X. 


2 


X) 


3 


(x) 


4 


[X] 


5 


<x> 


6 


[x] 



where x is the generated number or letter. 
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Note: mark must not contain ordinary (paddable) spaces 

because alignment of items will be lost if the right margin is ^ 

justified (see "Unpaddable Spaces")- \ 

• The U-space argument gives the number of blank lines (nrof f ) 
or halves of a vertical space (t rof f ) that should be generated 
by each . li macro in the list. If omitted, U-space defaults to 1; 
the value can be used to obtain compact lists. \f LI -space is 
greater than 0, the .LI macro issues a . ne request for two lines 
just before printing the mark. 

• The LB-space argument is the number of blank lines (nrof f ) or 
half vertical spaces (t rof f) to be generated by . lb itself. If 
omitted, LB-space defaults to 0. 

There are three combinations oi U-space and LB-space: 

• The normal case is to s&t U-space to 1 and LB-space to 
yielding one blank line (nrof f ) or one-half a vertical space 

(t rof f ) before each item in the list; such a list is usually f 

terminated with a . LE 1 macro to end the list with a blank line 
(n r o f f ) or one-half a vertical space (t r o f f ). 

• For a more compact list, U-space is set to 0, LB-space is set to 1, 
and the . LE 1 macro is used at the end of the Ust. The result is 
a list with one blank line (nrof f ) or one-half a vertical space 
(t rof f ) before and after it. 

• If both U-space and LB-space are set to and the . LE macro is 
used to end the list, a list without any blank lines will result. 

"User-Defined List Structures" shows how to build upon the supplied 
list of macros to obtain other kinds of lists. 

5.13 User-definedlist structures 

Note: This section is intended for users accustomed to writing 
formatter macros. 



If a large document requires complex list structures, it is useful to 
define the appearance for each list level only once instead of having to 
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define the appearance at the beginning of each list. This permits 
consistency of style in a large document. A generalized list- 
initialization macro might be defined in such a way that what the macro 
does depends on the list-nesting level in effect at the time the macro is 
called. Levels 1 through 5 of the lists to be formatted may have the 
following appearance: 

A. 

[1] 



a) 



The following code defines a macro ( . aL) that always begins a new 
list and determines the type of list according to the current list level. 
To understand it, the user should know that the number register : g is 
used by the mm list macros to determine the current list level; it is if 
there is no currently active list. Each call to a list-initialization macro 
increments : g, and each . LE call decrements it. 

.\" register g is used as a local 

.\" temporary to save :g before 

.\" it is changed below 

. de aL 

• nr g \\n (:g 

.if \\ng=0 .AL A \" produces an A. 

.if \\ng=l .LB \\n (Li 14 \" produces a [1] 

.if \\ng=2 .BL \" produces a bullet 

•if \\ng=3 .LB \\n (Li 2 2a \" produces an a) 

•if \\ng=4 .ML + \" produces a + 

This macro can be used (in conjunction with . LI and . LE) instead of 
. AL, . RL, . BL, . LB, and . ML. For example, the following input: 
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.AL 

.LI 

First line. 

.aL 

• LI 

Second line . 

.LE 

.LI 

Third line. 

.LE 

when foraiatted yields 

1. First line. 

[1] Second line. 

2. Third line. 

There is another approach to lists that is similar to the . H mechanism. 
List-initialization, as well as the .LI and the . LE macros, are all 
included in a single macro. That macro, defined as . bL below, 
requires an argument to tell it what level of item is required; it adjusts 
the list level by either beginning a new list or setting the list level back 
to a previous value, and then issues a . LI macro call to produce the 
item 

.de bL 

•ie \\n(.$ .nr g \\$1 

\" if there is an argument, that is the level 
. el .nr g \\n ( :g 

\" if no argument, use current level 
.if \\ng-\\n{:g>l .)D 

\" ** ILLEGAL SKIPPING OF LEVEL 

\" increasing level by more than 1 
.if \\ng>\\n(:g \{.aL Wng-l 

\" if g > :g, begin new list 
.nr g \\n ( : g\ } 

\" and reset g to current level 

\" ( . aL changes g) 
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.if \\n(:g>\\ng .LC \\ng 

\" if :g > g, prune back to correct level 
\" if :g = g, stay within current list 

.LI 

\" in all cases, get out an item 

For . bL to work, the previous definition of the . aL macro must be 
changed to obtain the value of g from its argument rather than from 
: g. Invoking . bL without arguments causes it to stay at the current 
list level. The . LC (list clear) macro removes list descriptions until the 
level is less than or equal to that of its argument. For example, the . H 
macro includes the call . LC . If text is to be resumed at the end of a 
list, insert the call . LC to clear out the lists completely. The 
example below illustrates the relatively small amount of input needed 
by this approach. The input text 

The quick brown fox jumped over the lazy dog's back. 

.bL 1 

First line. 

.bL 2 

Second line. 

.bL 1 

Third line. 

.bL 

Fourth line. 

.LC 

Fifth line. 

when formatted yields 

The quick brown fox jumped over the lazy dog's back. 

A. First line. 

[1] Second line. 

B. Third line. 

C. Fourth line. 
Fifth line. 
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6. Memorandum and released-paper style 
documents 

Note: Some of the information in this section is applicable to 
Bell Laboratories documents only. However, most of the 
features discussed here can be tailored to specific needs. 

One use of the Memorandum Macros is the preparation of memoranda 
and released-paper documents that have special requirements for the 
first page and for the cover sheet. Data needed (title, author, date, case 
numbers, and so forth) are entered the same for both styles; an 
argument to the . MT macro indicates which style is being used. 

6.1 Sequence of beginning macros 

If the following macros are present they must be given in the following 
order: 

. ND new-date 

. TL [charging-case] \filing-case] 
one or more lines of text 

. AF [company-name] 

• AU name [initials] [loc] [dept] [ext] [room] [arg] [arg] 
.AT [title] ... 

. TM [number] . . . 

.AS [arg] [indent] 

one or more lines of abstract text 

.AE 

• NS [arg] 

one or more lines of Copy to notation 

.NE 

.OK [keyword] ... 

.MT [type] [addressee] 
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The only required macros for a memorandum for j&le or a released- 
paper document are , TL, . AU, and . mt; all other macros (and their 
associated input lines) may be omitted if the features are not needed. 
Once . MT has been invoked, none of the above macros (except . NS 
and . NE) can be reinvoked because they are removed from the table of 
defined macros to save memory space. 

If neither the memorandum nor released-paper style is desired, the 
.TL, .AU, .TM, .AE, , OK, .MT, .ND,and . AF macros should be 
omitted from the input text. If these macros are omitted, the first page 
will have only the page header followed by the body of the document. 

6.2 Title 

The . TL macro generates a centered title. 

.TL [charging-case] \filing-case] 
one or more lines of title text 

Arguments to the . TL macro are the charging-case number(s) and 
filing-case number(s). 

• The charging-case argument is the case number to which time 
was charged for the development of the project described in the 
memorandum. Multiple charging-case numbers are entered as 
subarguments by separating each from the previous with a 
comma and a space and enclosing the entire argument within 
double quotes. 

• The, filing-case argument is a number under which the 
memorandum is to be filed. Multiple filing case numbers are 
entered similarly. For example, 

.TL "12345, 67890" 987654321 

Construction of a Table of Even Prime Numbers 

The title of the memorandum or released-paper document follows the 
. TL macro and is processed in fill mode. The . br request may be 
used to break the title into several lines as follows: 
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•TL 12345 

First Title Line 

.br 

\! .br 

Second Title Line 

On output, the title appears after the word "Subject" in the 
memorandum style and is centered and bold in the released-paper 
document style. 

If only a charging case number or only a filing case number is given, it 
will be separated from the title in the memorandum style by a dash and 
will appear on the same line as the title. If both case numbers are given 
and are the same, then "Charging and Filing case" followed by the 
number will appear on a line following the title. If the two case 
numbers are different, separate lines for "Charging Case" and "File 
Case" will appear after the title. 

6.3 Authors 

The . AU and . AT macros take arguments that describe an author. 

.AU name [initials] [loc] [dept] [ext] [room] [arg] [arg] 
.AT [title] ... 

If any argument contains blanks, that argument must be enclosed 
within double quotes. The first six arguments must appear in the order 
given. A separate . AU macro is required for each author. 

The . AT macro is used to specify the author's title. Up to nine 
arguments may be given. Each will appear in the signature block for 
memorandum style (see "End of Memorandum Macros") on a 
separate line following the signer's name. The . AT must immediately 
follow the . AU for the given author. For example, 

.AU "S. J. Jones" SJJ PY 9876 5432 lZ-234 
.AT Director "Materials Research Laboratory" 

In the "From" portion in the memorandum style, the author's name is 
followed by location and department number on one line and by room 
number and extension number on the next line. The "x" for the 
extension is added automatically. Printing of the location, department 
number, extension number, and room number can be suppressed on the 
first page of a memorandum by setting the register Au to 0; the default 



4-46 A/UX Text Processing Tools 



value for Au is 1. Arguments 7 through 9 of the . AU macro, if present, 
will follow this normal author information in the "From' ' portion, each 
on a separate line. These last three arguments can be used for 
organizational numbering schemes, and so on. For example, 

.AU "S. P. Lename" SPL IH 998 7766 5H-44 654-3210 . OlMF 

The name, initials, location, and department are also used in the 
signature block. Author information in the "From" portion, as well as 
names and initials in the signature block will appear in the same order 
as the .AU macros. 

Note: Names of authors in the released-paper style are centered 
below the title. Following the name of the last author, ' 'Bell 
Laboratories" and the location are centered. The paragraph on 
memorandum types contains information regarding authors 
from different locations (see "Memorandum Types"). 

6.4 TM numbers 

If the memorandum is a technical memorandum, the TM numbers are 
supplied via the .TM macro. 

.TM {number] ... 

Up to nine numbers may be specified. For example, 

.TM 7654321 11111111 

This macro call is ignored in the released-paper and external-letter 
styles (see "Memorandum Types"). 

6.5 Abstract 

If a memorandum has an abstract, the input is identified with the . AS 
(abstract start) and . AE (abstract end) delimiters. 

.AS \_arg\ [indent] 
text of abstract 

.AE 

Abstracts are printed on page one of a document, on its cover sheet or 
on both. There are three styles of cover sheet: 
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• released paper 

• technical memorandum 

• memorandum for file (also used for engineer's note, 
memorandum for record, and so forth) 

Cover sheets for released papers and technical memoranda are obtained 
by invoking the . CS macro (see "Cover Sheet"). 

In released-paper style (first argument of the . mt macro is 4) and in 
technical memorandum style, if the first argument of . AS is 

Abstract will be printed on page one and on the cover 
sheet (if any), 

1 Abstract will appear only on the cover sheet (if any). 
(See "Memorandum Types.") 

In memoranda for file style and in all other documents (other than 
external letters), if the first argument of . as is 

Abstract will appear on page one and there will be no 
cover sheet printed, 

2 Abstract will appear only on the cover sheet which will 
be produced automatically (that is, without invoking the 
. CS macro). 

It is not possible to get either an abstract or a cover sheet with an 
external letter (first argument of the . MT macro is 5). 

Notations such as a "Copy to" list are allowed on memoranda for file 
cover sheets; the . NS and . ne macros must appear after the . as 2 
and . AE macros. Headings and displays are not permitted within an 
abstract. (See "Copy To and Other Notations," "Numbered 
Headings," "Unnumbered Headings" and "Displays.") 

The abstract is printed with ordinary text margins; an indentation to be 
used for both margins can be specified as the second argument of .AS. 
Values that specify indentation must be unsealed and are treated as 
"character positions," that is, as the number of ens. 
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6.6 Other keywords 

Topical keywords may be specified on a technical memorandum cover 
sheet using the .OK macro. 

.OK [keyword] ... 

Up to nine such keywords or keyword phrases can be specified as 
arguments to the . OK macro; if any keyword contains spaces, it must 
be enclosed within double quotes. 

6.7 Memorandum types 

The . MT macro controls the format of the top part of the first page of a 
memorandum or of a released-paper document and the format of the 
cover sheets. 

.MT [type] [addressee] 

The type arguments and corresponding values are 

" " No memorandum type printed 

No memorandum type printed 

none memorandum for file is printed 

1 MEMORANDUM FOR F I LE is printed 

2 PROGRAMMER'S NOTES is printed 

3 ENGINEER'S NOTES is printed 

4 Released-paper style 

5 External-letter style 

" string " string is printed 

If the type argument indicates a memorandum style document, the 
corresponding statement indicated under Value will be printed after the 
last line of author information. If type is longer than one character, 
then the string itself will be printed. For example, 

.MT "Technical Note #5" 

A simple letter is produced by calling . MT with a null (but not omitted) 
or argument. 
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The second argument to . MT is the name of the addressee of a letter. If 
present, that name and the page number replace the normal page header 
on the second and following pages of a letter. For example, 

.MT 1 "Steve Jones" 

produces 

Steve Jones - 2 

The addressee argument cannot be used if the first argument is 4 
(released-paper style document). 

The released-paper style is obtained by specifying 

.MT 4 [1] 

This results in a centered, bold title followed by centered names of 
authors. The location of the last author is used as the location 
followmg "Bell Laboratories" (unless the . AF macro specifies a 
different company). If the optional second argument to . MT 4 is 
given, the name of each author is followed by the respective company 
name and location. Information necessary for the memorandum style 
document but not for the released-paper style document is ignored. 

If the released-paper style document is used, most Bell Telephone 
Laboratories location codes are defined as strings that are the addresses 
of the corresponding BTL locations. These codes are needed only until 
the .MT macro is invoked. Thus, following the .MT macro, the user 
may reuse these string names. In addition, the macros for the end of a 
memorandum (see "End of Memorandum Macros") and their 
associated lines of input are ignored when the released-paper style is 
specified. 

Authors from non-BTL locations may include their affiliations in the 
released-paper style by specifying the appropriate . AF macro (see 
"Alternate First-Page Format' ') and defining a string (with a 2- 
character name such as zz) for the address before each . AU. For 
example. 
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.TL 

A Learned Treatise 

.AF "Get em Inc." 

.ds ZZ "22 Maple Avenue, Sometown 9999" 

.AU "F. Swatter" "" ZZ 

•AF "Bell Laboratories" 

.AU "Sam P. Lename" "" CB 

.MT 4 1 

In the external-letter style document, only the title without the word 
"Subject:" and the date are printed in the upper left and right comers, 
respectively, on the first page. It is expected that preprinted stationery 
win be used with the company logo and address of the author. 

6.8 Date changes 

The . ND macro alters the value of the string dt, which is initially set 
to produce the current date. 

.ND new-date 

If the argument contains spaces, it must be enclosed within double 
quotes. 

6.9 Alternate first-page format 

An alternate first-page format can be specified with the . AF macro. 

.AF [company-name] 

The words "Subject," "Date," and "From" (in the memorandum 
style) are omitted and an altemate company name is used. 

If an argument is given, it replaces "Bell Laboratories" without 
affecting other headings. If the argument is null, "Bell Laboratories" 
is suppressed; and extra blank lines are inserted to allow room for 
stamping the document with a Bell System logo or a Bell Laboratories 
stamp. 

The . AF with no argument suppresses "Bell Laboratories" and the 
"Subject/Date/From" headings, allowing output on preprinted 
stationery. The use of . AF with no arguments is equivalent to the use 
of -rAl except that the latter must be used if it is necessary to change 
the line length, page offset, or both (these default to 5.8i and li, 
respectively, for preprinted forms). The flag options -rOk and -rWk 
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.AU 


"J. 


R 


.AU 


"E. 


C 


.AU 


"N. 


W 


.MT 


4 





are not effective with . af. The only . af use appropriate for the 
trof f formatter is to specify a replacement for "Bell Laboratories". 
The flag option -rEn controls the font of the "Subject/Date/From" 
block. (See "Parameters Set From Command Line.") 

6.10 Example 

Input text for a document may begin as follows: 

.TL 

MM\* (EMMemorandum Macros 

.AU "D. W. Smith" DWS PY 
Mashey" JRM PY 

Pariser (January 1980 Rev.)" ECP PY 
Smith (June 1980 Rev.)" NWS PY 

Figures 4-1, 4-2, and 4-3 at the end of this chapter show the input text 
file for a simple letter as well as the formatted output from both the 
nrof f and trof f formatters. 

6.1 1 End of Memorandum Macros 

At the end of a memorandum document, signatures of authors and a list 
of notations can be requested. The following macros and their input 
are ignored if the released-paper style document is selected. 

6.11.1 Signature block 

The . FC and . SG macros print a formal closing and signature block. 

• FC [closing] 

• SG [arg] [1] 

The . FC macro prints "Yours very truly," as a formal closing, if no 
closing argument is used. It must be given before the .SG macro. A 
different closing may be specified as an argument to . FC. 

The . SG macro prints the author's name after the formal closing, if 
any. Each name begins at the center of the page. Three blank lines are 
left above each name for the actual signature. 

• If no arguments are given, the line of reference data (location 
code, department number, author's initials, and typist's initials 
all separated by hyphens) will not appear. 
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• A non-null first argument is treated as the typist's initials and is 
appended to the reference data. 

• A null first argument prints reference data without the typist's 
initials or the preceding hyphen. 

• If there are several authors and if the second argument is given, 
reference data is placed on the line of the first author. 

Reference data contains only the location and department number of 
the first author. Thus, if there are authors from different departments or 
from different locations, the reference data should be supplied 
manually after the invocation (without arguments) of the . SG macro. 
For example, 

.SG 

. rs 

. sp -Iv 

PY/MH-987 6/5432-JJJ/SPL-cen 

6.1 1 .2 "Copy to" and other notations 

Many types of notations (such as a list of attachments or "Copy to" 
lists) may follow signature and reference data. Various notations are 
obtained through the . NS macro, which provides for proper spacing 
and for breaking notations across pages, if necessary. 

• NS [arg] 

zero or more lines of the notation 

.NE 

Codes for arg and the corresponding notations are 
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Argument 


Notation 


none 

IT IT 



1 

2 
3 


Copy to 

Copy to 

Copy to 

Copy (with att.) to 

Copy (without att.) to 

Att. 


4 


Atts. 


5 


Enc. 


6 


Encs. 


7 
8 


Under Separate Cover 
Letter to 


9 


Memorandum to 


"string" 


Copy (string) to 



If arg consists of more than one character, it is placed within 
parentheses between the words "Copy" and "to". For example, 

.NS "with att. 1 only" 

will generate 

Copy (with att. 1 only) to 

as the notation. More than one notation may be specified before the 
. NE macro because a . NS macro terminates the preceding notation, if 
one exists. For example, 

.NS 4 

Attachment 1-List of register names 

Attachment 2-List of string and macro names 

.NS 1 

S. J. Jones 

.NS 2 

S . P • Lename 

G. H. Hurtz 

.NE 

would be formatted as 
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Atts. 

Attachment 1-List of register names 

Attachment 2-List of string and macro names 

Copy (with att) to 
S. J. Jones 

Copy (without att.) to 
S. P. Lename 
G. H. Hurtz 

The . NS and . ne macros can also be used following . as 2 and . ae 
to place the notation list on the memorandum for file cover sheet (see 
* 'Abstract' '). If notations are given at the beginning without .AS 2 , 
they will be saved and generated at the end of the document. 

6.11.3 Approval signature line 

The . AV macro can be used after the last notation block to 
automatically generate a line with spaces for the approval signature and 
date. 

• AV approver' s-name 

For example, 

.AV "Jane Doe" 
produces 

APPROVED: 



Jane Doe Date 

6.12 One-page letter 

To increase the page length temporarily, for example, to force space for 
a signature at the bottom of a letter, you can use the -rLn flag option. 
For example, using -rL9 has the effect of making the formatter 
believe that the page is 90 lines long and therefore providing more 
space than usual to place the signature or the notations. 
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Note: This will work only for a single-page letter or memo. 

6.13 Define file information 

The /usr/lib/macros/strings . mm file contains pre-defined 
strings for the . MT and . PM macros. These strings are proprietary 
disclaimers for AT&T Bell Laboratories, and may be redefined by 
system administrators to contain different string and font information. 
Only system administrators have write permissions to change the define 
file. 

6.14 Business letter styie 

An alternative to the format memorandum style is the business letter 
style, which produces four types of business letters: blocked, 
semiblocked, full-blocked, and simpUfied. 

6.14.1 Letter-type macro 

The letter-type macro . lt formats a letter in one of four business 
styles: 

• LT [arg\ 

. LT accepts one optional argument. Arguments and corresponding 
format are as follows: 

Argument Format 



none 


blocked 


BL 


blocked 


SB 


semiblocked 


FB 


full-blocked 


SP 


simplified 



. LT controls the placement on the page of the output of the 
subordinate macro . LO and the subordinate macro pairs ( . lA and 
. IE, . WA and . WE), which differs according to each of the four 
business letter formats. 

Business letter and formal memorandum macros ( . LT and . mt) are 
mutually exclusive. If you specify both . LT and . MT specific macros 
in a single document, nrof f/trof f attempts to process the file 
according to the first formatting specific macro it encounters, mm 
ignores . MT-specific macros and . MT-specific command line 
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parameters if you use them with . lt; conversely, if you use . lt- 
specific macros with , MT, mm ignores them. 

If you use these business letter macros, the macro pairs, . WA/ . we, and 
. I a/. IE, and the page formatting macros . lt are required; all other 
business letter macros are optional. 

The . LT macro arguments control paragraph indentation for each of 
the four letter types. If you redefine the Pt and Pi registers, the user- 
specified indentations will override. Specification of the Pt and Pi 
registers must occur after specification of the . lt macros. 

• In the block format all lines of text begin at the left margin 
except the dateline, return address, closing, and writer's 
identification. These begin at the center of the line. (The center 
of the line is not a fixed point, it is calculated for the current line 
length.) 

• The semiblocked format is the same as the blocked format; 
except the first line of each paragraph is indented five spaces. 

• In full-blocked format all lines begin at the left margin. There 
are no exceptions. 

• The simplified format is the same as the full-blocked format; 
except the salutation is replaced by an all-capital subject fine and 
is followed by an additional blank line, the closing is omitted, 
and the writer's identification is in all-capital letters on one line. 

The following table presents a synopsis of the placement of business 
letter components for the four . lt letter formats, and lists the macros 
(which are explained in detail below) that you use to format those 
components. 



mm Reference 4-57 



Macro and function BL 



SB 



FB SP 



.WA/.WE 

Writer's address 


center 


center 


left 


left 


.LO CN [arg] 
Confidential notation 


left 


left 


left 


left 


.LO RN[arg] 
Reference notation 


center 


center 


left 


left 


.lA/.IE 

Inside address 


left 


left 


left 


left 


.LO AT [arg] 
Attention 


left 


left 


left 


left 


.LO SA [arg] 
Salutation 


left 


left 


left 


none 


.LO SJ [arg] 
Subject line 


left 


indented 


left 


left 


.P 
Paragraphs 


left 


indented 


left 


left 


.FC 
Closing 


center 


center 


left 


left 


.SG 
Signature 


center 


center 


left 


left 



.NS/.NE 
Copy notation 



left 



left 



left left 



There are two possible error conditions for the . LT macro: 

• If you omit the . LT macro, file processing aborts and an 
appropriate error message prints. 

• If mm does not recognize an argument to . LT, the file processing 
aborts and an appropriate error message prints. 

6.14.2 Writer's address macros 

Use this macro pair to specify the writer of the letter and the writer's 
return address. 
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• WA writer-name [title] 
return address 

.WE 

For example, 

•WA "James Lorrin, Ph.D." Director 
Summit Research Company- 
SB River Road 
Summit, New Jersey 07 901 
.WE 

If a complete return address is not necessary for the letter (for example, 
if you use printed letterhead stationary) you can specify the writer 
information alone: 

-WA "James Lorrin, Ph.D." Director 
.WE 

The return address cannot exceed 14 lines. Lines in the return address 
that follow line 14 do not appear on the letter. 

The two arguments specified for the . WA and . we macro pair, the 
writer-name and the title, provide information used by die . SG macro. 
If you do not specify the . SG macro, the writer's name does not appear 
on the letter. 

For the case of multiple writers on a single letter, you may specify only 
one writer return address. The specified writer return address must 
appear with the first writer-name as the first invocation of the . WA/ . WE 
macro pair. Later return address specifications do not appear on the 
letter, although any number of additional writer names may be 
specified. For example, 
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.WA "James Lorrin^ Ph.D." Director 

Summit Research Company 

38 River Road 

Summit, New Jersey 07 901 

.WE 

.WA "John Smith" Supervisor 

.WE 

.WA "Diane Kane" "Technical Support" 

.WE 

For blocked and semiblocked letter styles the writer return address 
begins on line 12 of the first page and each line begins at the center of 
the line. For the full-blocked and simplified letter styles the writer 
return address begins on line 12 of the page and each line begins at the 
left margin. 

Note: Top of page processing can be controlled directly 
through nrof f . The beginning of the printed page is user- 
defined. See the requests .whand .ch in "nroff/trof f 
Reference," 

If you omit either or both of the . WA and . WE macros, the file 
processing aborts and an appropriate error message prints. 

6.14.3 Inside address macros 

. I A and . IE are a macro pair that you use to specify the addressee 
and the addressee's address. There are two ways that you can use this 
macro pair: 

.lA 
text 

.IE 

or 

. I A [addressee-name] [title] 
text 

.IE 

For example, 
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or 



• lA 

Fred Smith, Ph.D. 
Columbia University 
116th Street 

New York, New York 10019 
.IE 



lA "Fred Smith, Ph.D 
IE 



For all four styles of . LT, the inside address prints on the fifth line 
below the date (if a reference notation or confidential notation appears 
after the date, the inside address prints three lines below the notation) 
and each line begins at the left margin. 

If you omit either or both of the . lA and . IE macros, the file 
processing aborts and an appropriate error message prints. 

6.14.4 Letter-options macro 

The letter-options macro provides the capabiUty for specifying five 
common business letter components: 

.LO type [arg] 

The . LO macro takes care of placement and spacing of these letter 
components for each . LT letter format. . LO requires one argument to 
specify a letter component type, and accepts one optional string 
argument to refine its action. . LO's arguments and their corresponding 
components are below: 

CN confidential notation 

RN reference notation 

AT attention 

SA salutation 

SJ subject line 

6.14.4.1 Confidential notation 

The confidential notation shows that a business letter should be read 
only by the person to whom it is addressed. The confidential notation 
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appears on the second line below the date line of the letter and begins 
at the left margin for aU letter formats. 

If the optional string argument is present the specified string replaces 
the default. For example, 

.LO CN "RESTRICTED" 

The default of CN prints CONFIDENTIAL. 

6.14.4.2 Reference notation 

The reference notation supplies specific information to be used by the 
addressee. For example, 

.LO RN "meeting of 1/25" 

The reference note appears two lines below the dateline of the letter or 
on the second line below any notation that follows the date and is left 
aligned with the dateUne for all four letter formats. 

RN provides a common format for including a reference note by 
printing the string "In reference to :" preceding the optional 
string argument to .LO. The format string "In reference to:" 
cannot be redefined. There is not a default value for the optional 
argument. 

6.14.4.3 Attention 

The attention line directs the letter to the attention of a specific person 
or department. For example, 

.LO AT "Dr. Smith" 

The attention information appears on the second fine below the inside 
address of the letter and begins at the left margin. 

AT provides a common format for directing a letter to the attention of a 
specific person by printing the string "ATTENTION : " preceding the 
optional string argument to . LO. The format string "attention : " 
cannot be redefined. There is not a default value for the optional 
argument. 

6.14.4.4 Salutation 

The salutation specifies the letter's opening greeting. For the blocked, 
semiblocked, and the full-blocked formats the salutation appears on the 
second fine below the inside address (or on the second line below the 
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attention line, if used). In the simplified letter format, the salutation is 
ignored. 

Thedefaultof SAprints "To whom It May Concern:" for the 
salutation. If the optional string argument is present the specified string 
will replace the default. For example, 

.LO SA "Dear Dr. Smith" 

6.14.4.5 Subject line 

The subject line shows what the letter is about. In the blocked and 
full-blocked letter formats the subject line information appears on the 
second line below the salutation and begins at the left margin. For the 
semi-blocked format the subject line appears on the second line below 
the salutation and is indented five spaces. In the simplified letter 
format the subject line information appears in place of the salutation 
three lines below the inside address of the attention line; the salutation, 
if you use it, is ignored. 

For the blocked, semiblocked, and full-blocked formats, S J provides a 
common format for indicating what the letter is about by printing the 
string "SUBJECT : " preceding the optional string argument to . LO. 

.LO SJ "Staff Meeting" 

The format string ' * SUBJECT : ' ' cannot be redefined. There is not a 
default value for the optional argument. 

For the simplified letter, the subject line string argument prints on the 
third line below the inside address or the attention line (a salutation is 
ignored if used). 

If you specify the . LO macro without an argument or the argument you 
specify is unrecognized, the file processing aborts and an appropriate 
error message prints. 

6.14.5 Multipage letters 

The . LT macro controls the format for the first page of the letter. The 
letter macros will not alter the default nrof f/trof f page processing 
following the first page of the letter. 

6.14.6 Sequence of beginning letter macros 

Macros . WA, , we, . ia, . IE, and . LT must be given in the order 
listed in the following table. . LO can be specified multiple times with 
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different argument types. The . LO argument types do not have to be in 
any specific order. All . LO requests must be specified before . LT. 

.ND new date 
.WA writer' s name {title] 
Return address 
Street 

City, State Zip Code 
Text 

.WE 
.lA 

Addressee name 

Title 

Company 

Street 

City, State Zip Code 

Text 

.IE 

. LO type [arg] 

.LT [arg] 

• P 
Text 
.FC 

• SG [arg{\]] 
.NS [arg [I]] 
Text 

.NE 

If you put nrof f /t rof f requests and lines of text before . LT, you 
change how . LT works. For example, if the first line of a file is a line 
of text, mm processes the file as if you had not specified . LT. 

7. Displays 

Displays are blocks of text that are to be kept together on a page and 
not split across pages. They are processed in an environment that is 
different from the body of the text (see the . ev request in 
"nrof f/trof f Refererence")- The Memorandum Macros package 
provides two styles of displays — a static ( . DS) style and a floating 
(.DF) style. 
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• In the static style, the display appears in the same relative 
position in the output text as it does in the input text. This may 
result in extra white space at the bottom of the page if the display 
is too long to fit in the remaining page space. 

• In the floating style, the display "floats" through the input text to 
the top of the next page if there is not enough space on the 
current page. Thus input text that follows a floating display may 
precede it in the output text. A queue of floating displays is 
maintained so that their relative order of appearance in the text is 
not disturbed. 

By default, a display is processed in no-fill mode with single spacing 
and is not indented from the existing margins. The user can specify 
indentation or centering as well as fill-mode processing. 

Note: Displays and footnotes can never be nested in any 
combination. Although lists and paragraphs are permitted, no 
headings ( . H or . HU) can occur within displays or footnotes. 

7.1 Static displays 

A static display is started by the . DS macro and terminated by the . DE 
macro. 

.DS \format\ [fill] [rindent] 
one or more lines of text 

.DE 

With no arguments, . DS accepts lines of text exactly as typed (no-fill 
mode) and will not indent lines from the prevailing left margin 
indentation or from the right margin. 

• The, format argument is an integer or letter used to control the 
left margin indentation and centering with the following 
meanings: 
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<l II 


no indent 


omitted 


no indent 


OorL 


no indent 


ion 


indent by standard amount 


2 ore 


center each line 


3orCB 


center as a block 



• The fill argument is an integer or letter and can have the 
following meanings: 

fill Meaning 

" " no-fill mode 

omitted no-fill mode 

or N no-fill mode 

1 or F fill mode 

• The rindent argument is the number of characters that the fine 
length should be decreased, that is, an indentation from the right 
margin. This number must be unsealed in the nrof f formatter 
and is treated as ens. It may be scaled in the trof f formatter or 
else it defaults to ems. 

The standard amount of static display indentation is taken from the S i 
register, a default value of five spaces. Thus, text of an indented 
display aligns with the first line of indented paragraphs, whose indent is 
contained in the Pi register (see "Paragraphs"). Even though their 
initial values are the same default values, these two registers are 
independent. 

The display /or/naf argument value 3 (or CB) horizontally centers the 
entire display as a block, as opposed to . DS 2 and . DF 2, which 
center each fine individually. All collected fines are left justified, and 
the display is centered based on the width of the longest fine. This 
format must be used in order for the eqn/neqn mark and Hneup 
feature to work with centered equations (see "Equations"). 

By default, a blank line (nrof f ) or one-half a vertical space (t rof f ) 
is placed before and after static and floating displays. These blank 
lines before and after static displays can be inhibited by setting the 
register Ds toO. 
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The following example shows usage of all three arguments for static 
displays. This block of text will be indented five spaces (ems in 
trof f ) from the left margin, filled, and indented five spaces (ems in 
trof f ) from the right margin (that is, centered). The input text 

.DS I F 5 

^ *We the people of the United States, 

in order to form a more perfect union, 

establish justice, ensure domestic tranquillity, 

provide for the common defense, 

and secure the blessings of liberty to 

ourselves and our posterity, 

do ordain and establish this Constitution to the 

United States of America.'' 

• DE 

produces the output 

"We the people of the United States, in order to form a more 
perfect union, establish justice, ensure domestic tranquillity, 
pjrovide for the common defense, and secure the blessings of 
liberty to ourselves and our posterity, do ordain and establish 
this Constitution to the United States of America." 

7.2 Floating displays 

A floating display is started by the . DF macro and terminated by the 
. DE macro. 

.DF \format] [fill] [rindent] 
one or more lines of text 

.DE 

Arguments have the same meanings as static displays described above, 
except indent, no indent, and centering are calculated with respect to 
the initial left margin. This is because prevailing indent may change 
between when the formatter first reads the floating display and when 
the display is printed. One blank line (nrof f ) or one-half a vertical 
space (trof f ) occurs before and after a floating display. 

The user may exercise precise control over the output positioning of 
floating displays through the use of two number registers, De and Df 
(see below). When a floating display is encountered by the nrof f or 
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t rof f fonnatter, it is processed and placed onto a queue of displays 
waiting to be generated. Displays are removed from the queue and 
printed in the order entered, which is the order they appeared in the 
input laie. If a new floating display is encountered and the queue of 
displays is empty, the new display is a candidate for immediate output 
on the current page. Immediate output is governed by size of display 
and the setting of the Df register code. The De register code controls 
whether text will appear on the current page after a floating display has 
been produced. 

As long as the display queue contains one or more displays, new 
displays will be automatically entered there, rather than being 
generated. When a new page is started, or the top of the second 
column in 2-column mode, the next display from the queue becomes a 
candidate for output if the Df register code has specified top-of-page 
output. When a display is generated, it is also removed from the queue. 

When the end of a section (using section-page numbering) or the end of 
a document is reached, all displays are automatically removed from the 
queue and are generated. This occurs before a .SG, ,CS,or .TC 
macro is processed. 

A display will fit on the current page if there is enough room to contain 
the entire display or if the display is longer than one page in length and 
less than half of the current page has been used. A wide (full-page 
width) display will not fit in the second column of a 2-column 
document. 

The De and Df number register code settings and actions are as 
follows: 
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De Register 
Code Action 

No special action occurs (also the default condition). 

1 A page eject will always follow the output of each 
floating display, so only one floating display will appear 
on a page and no text will follow it. 

Note: For any other code, the action performed is the same as 
for code 1. 

Df Register 
Code Action 

Floating displays will not be generated until end of 
section (when section-page numbering) or end of 
document. 

1 Generate new floating display on current page if there is 
space; otherwise, hold it until end of section or document. 

2 Generate exactly one floating display from queue to the 
top of a new page or column (when in 2-column mode). 

3 Generate one floating display on current page if there is 
space; otherwise, output to the top of a new page or 
column. 

4 Generate as many displays as will fit (but at least one) 
starting at the top of a new page or column. 

If the De register is set to 1, each display wiU be followed 

by a page eject, causing a new top of page to be reached 
where at least one more display will be generated (this 
also applies to code 5), 

5 Generate a new floating display on the current page if 
there is room (default condition). Generate as many 
displays (but at least one) as will fit on the page starting at 
the top of a new page or column. 
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Note: For any code greater than 5, the action performed is the 
same as for code 5. If the De register is set to 1, each display 
will be followed by a page eject, causing a new top of page to 
be reached where at least one more display will be generated. 

The . WC macro (see "Two-Column Output") can also be used to 
control handling of displays in double-column mode and to control the 
break in text before floating displays. 

7.3 Tables 

The mm macros interact with the tbl macros and provide some extra 
functionality (see "tbl Reference" for a description of the tbl 
program). 

.TS [H] 
global options ; 
column descriptors . 
title lines 

[.TH [N]] 

data within the table . 

.TE 

The . TS (table start) and . TE (table end) macros make possible the 
use of the tbl(l) program. These macros are used to delimit text to be 
examined by tbl and to set proper spacing around the table. 

The display function and the tbl dehmiting function are independent. 
In order to permit the user to keep together blocks that contain any 
mixture of tables, equations, filled text, unfilled text, and caption fines, 
the . TS/ . TE block should be enclosed within a display ( . DS/ . de). 
Roating tables may be enclosed inside floating displays ( . DF/ . de). 

Macros . TS and . TE permit processing of tables that extend over 
several pages. If a table heading is needed for each page of a 
multipage table, the H argument should be specified to the . TS macro 
as above. FoUowing the options and format information, the table title 
is typed on as many fines as required and is foUowed by the . th 
macro. The . TH macro must occur when .TS His used for a 
multipage table. This is not a feature of tbl but of the definitions 
provided by the Memorandum Macros package. 
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The . TH (table header) macro may take as an argument the letter N, 
This argument causes the table header to be printed only if it is the JSrst 
table header on the page. This option is used when it is necessary to 
build long tables from smaller . TS H/. te segments. For example, 

.TS H 

global options; 
column descriptors . 
title lines 

.TH 
data 

.TE 
• TS H 

global options ; 
column descriptors . 
title lines 

.TH N 

data 

.TE 

causes the table heading to appear at the top of the first table segment 
and no heading to appear at the top of the second segment when both 
appear on the same page. However, the heading will still appear at the 
top of each page that contains the table. This feature is used when a 
single table must be broken into segments because of table complexity 
(for example, too many blocks of filled text). If each segment had its 
own . TS H/ . TH sequence, it would have its own header. However, if 
each table segment after the first uses . TS H/ . th n, the table header 
will appear only at the beginning of the table and the top of each new 
page or column that contains the table. 

For the nrof f formatter, the -e flag option (-E for niin(l)) can be 
used for terminals, for instance the 450, that are capable of finer 
printing resolution. This will cause better alignment of features such as 
the lines forming the comer of a box. The -e flag option is not 
effective with col(l). (See "The mm Command.") 
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7.4 Equations 

Mathematical typesetting programs eqn/neqn(l) expect to use the 
. EQ (equation start) and . en (equation end) macros as delimiters in 
the same way that tbl(l) uses . TS and . TE; however, when 
processed with the mm macros, . EQ and . EN must occur inside a 
. DS/. DE pair. There is an exception to this rule — if . EQ and . en are 
used to specify only the delimiters for in-hne equations or to specify 
eqn/neqn defines, the . DS and . DE macros must not be used; 
otherwise, extra blank lines wUl appear in the output. 

.DS 

.EQ [label] 
equation(s) 

.EN 
.DE 

The . EQ macro takes an argument that will be used as a label for the 
equation. By default, the label will appear at the right margin in the 
vertical center of the general equation. The Eq register can be set to 1 
to change labeling to the left margin. 

The equation will be centered for centered displays; otherwise, the 
equation will be adjusted to the opposite margin from the label. 

7.5 Figure, table, equation, and exiiibit tities 

The . FG (figure title), . tb (table title), . EC (equation caption), and 
. EX (exhibit caption) macros are normally used inside . DS/. DE pairs 
to automatically number and print captions for figures, tables, and 
equations. 

.FG [title] [override] [flag] 

.TB [title] [override] [flag] 

.EC [title] [override] [flag] 

.EX [title] [override] [flag] 

These macros use registers Fg, Tb, Ec, and Ex, respectively (See 
' 'Parameters Set From Command Line' ' on -rN5 to reset counters in 
sections.) For example, 

.FG "This is a Figure Title" 

yields 
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Figure 1. This is a Figure Title 

The .TB macro replaces "Figure" with "TABLE," the .EC macro 
replaces "Figure" with "Equation," and the . EX macro replaces 
"Figure" with "Exhibit." The output title is centered if it can fit on a 
single line; otherwise, all lines but the first are indented to line up with 
the first character of the title. The format of the numbers can be 
changed using the . af request of the formatter. By setting the Of 
register to 1, the format of the caption may be changed from 

Figure 1. title 

to 

Figure 1 - title 

The override argument is used to modify normal numbering. If the ^a^ 
argument is omitted or 0, override is used as a prefix to the number; if 
the, flag argument is 1, override is used as a suffix; and if th& flag 
argument is 2, override replaces the number. If -rN5 is given, 
"section-figure" numbering is set automatically and user-specified 
override argument is ignored. (See "Parameters Set From Command 
Line.") 

As a matter of formatting style, table headings are usually placed above 
the text of tables, while figure, equation, and exhibit titles are usually 
placed below corresponding figures and equations. 

7.6 List of figures, tables, equations, and exhibits 

Lists of figures, tables, exhibits, and equations are printed following the 
table of contents if the number registers Lf , Lt, Lx, and Le 
(respectively) are set to 1. The Lf , Lt, and Lx registers are 1 by 
default; Le is by default. 

Titles of these lists can be changed by redefining the following strings, 
which are shown here with their default values: 

.ds Lf LIST OF FIGURES 

.ds Lt LIST OF TABLES 

.ds Lx LIST OF EXHIBITS 

.ds Le LIST OF EQUATIONS 
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8. Footnotes 

There are two macros ( . FS and . FE) that delimit text of footnotes, a 

string (F) that automatically numbers footnotes, and a macro ( . fd) 

that specifies the style of footnote text. Footnotes are processed in an \ 

environment different from that of the body of text (refer to . ev 

request in "nrof f/trof f Reference"). 

8.1 Automatic numbering of footnotes 

Footnotes may be automatically numbered by typing the three 
characters \ *F (that is, invoking the string f) immediately after the 
text to be footnoted without any intervening spaces. This will place the 
next sequential footnote number (in a smaller point size) a half line 
above the text to be footnoted. 

8.2 Delimiting footnote text 

.FS [label] 

one or more lines of footnote text 

.FE 

There are two macros that delimit the text of each footnote. The . FS 

(footnote start) macro marks the beginning of footnote text, and the i 

. FE (foomote end) macro marks the end. The label on the . FS macro, 

if present, will be used to mark footnote text. Otherwise, the number 

retrieved from the string F will be used. Automatically numbered and 

user-labeled foomotes can be intermixed. If a footnote is labeled ( . FS 

label), the text to be footnoted must be followed by label, rather than 

by \ *F. Text between . FS and . FE is processed in fill mode. 

Another . FS, a . DS, or a . DF is not permitted between . FS and . FE 

macros. If footnotes are required in the title, abstract, or table (see 

"Tables"), only labeled footnotes will appear properly. Everywhere 

else automatically numbered footnotes work correctly. For example, 

the input for an automatically numbered footnote is 

This is the line containing the word.\*F 

.FS 

This is the text of the footnote . 

.FE 

to be footnoted and automatically numbered. i 

and the input for labeled footnote is: 
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This is a labeled* 

.FS * 

The footnote is labeled with an asterisk. 

.FE 
footnote. 

Text of the fcx)tnote (enclosed within the . FS / . FE pair) should 
immediately follow the word to be footnoted in the input text, so that 
\ *F or label occurs at the end of a line of input and the next line is the 
. FS macro call. It is also good practice to append an unpaddable 
space (see "Unpaddable Spaces") to \*F or label when they follow 
an end-of-sentence punctuation mark (a period, question mark, or 
exclamation point). 

8.3 Format style of footnote text 

Within footnote text, the user can control formatting style by specifying 
text hyphenation, right margin justification, and text indentation, as 
well as left or right justification of the label when text indenting is used. 
The . FD macro is invoked to select the appropriate style. 

.FD [arg] [1] 

The first argument {arg) is a number from the left column of the 
following table. Formatting style for each number is indicated in the 
remaining four columns. Further explanation of the first two of these 
columns is given in the definitions of the .ad, .na, .hy, and .nh 
(adjust, no adjust, hyphenation, and no hyphenation, respectively) 
requests in "nrof f/trof f Reference." 
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Text Label 
Argument Hyphenation Adjust indent justification 






.nh 


.ad 


yes 


left 


1 


.hy 


.ad 


yes 


left 


2 


.nh 


.na 


yes 


left 


3 


.hy 


.na 


yes 


left 


4 


.nh 


.ad 


no 


left 


5 


.hy 


.ad 


no 


left 


6 


.nh 


.na 


no 


left 


7 


.hy 


.na 


no 


left 


8 


.nh 


.ad 


yes 


right 


9 


.hy 


.ad 


yes 


right 


10 


.nh 


.na 


yes 


right 


11 


.hy 


.na 


yes 


right 



If the first argument to . FD is greater than 11, the effect is as if . FD 
were specified. If the first argument is omitted or nuU, the effect is 
equivalent to . FD 1 in the nrof f formatter and to . FD in the 
trof f formatter; these are also the respective initial default values. 

If the second argument is specified, then when a first-level heading is 
encountered, automatically numbered footnotes begin again with 1. 
This is most useful with the section-page page numbering scheme. As 
an example, the input line 

.FD "" 1 

maintains the default formatting style and causes footnotes to be 
numbered afresh after each first-level heading in a document. 

Hyphenation across pages is inhibited by mm except for long footnotes 
that continue to the following page. If hyphenation is permitted, it is 
possible for the last word on the last line on the current page footnote 
to be hyphenated. The user has control over this situation by 
specifying an even . FD argument. 

Footnotes are separated from the body of the text by a short line rule. 
Those that continue to the next page are separated from the body of the 
text by a full- width rule. In the trof f formatter, footnotes are set in 
type two points smaller than the point size used in the body of text. 
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8.4 Spacing between footnote entries 

Normally, one blank line (nrof f ) or a 3-point vertical space (t rof f ) 
separates footnotes when more than one occurs on a page. To change 
this spacing, the Fs number register is set to the desired value. For 
example, 

.nr Fs 2 

will cause two blank lines (nrof f ), a 6-point vertical space (t rof f ) 
to occur between foomotes. 

9. Page headers and footers 

Text printed at the top of each page is called a page header. Text 
printed at the bottom of each page is called a page footer. There can 
be up to three lines of text associated with the header — every page, 
even page only, and odd page only. Thus the page header may have up 
to two lines of text — the line that occurs at the top of every page and 
the line for the even- or odd-numbered page. The same is true for the 
page footer. 

This part describes the default appearance of page headers and page 
footers and ways of changing them. The term header (not qualified by 
even or odd) is used to mean the page header line that occurs on every 
page, and similarly for the term footer. 

9.1 Defauit headers and footers 

By default, each page has a centered page number as the header. There 
is no default footer and no even or odd default headers or footers 
except as specified in "Default Header and Footer with Section-Page 
Numbering." 

In a memorandum or a released-paper style document, the page header 
on the first page is automatically suppressed provided a break does not 
occur before the . mt macro is called. Macros and text in the following 
categories do not cause a break and are permitted before the 
memorandum type ( . MT) macro: 

• Memorandum and released-paper style document macros ( . TL, 

.AU, .AT, .TM, .AS, .AE, .OK, .ND, .AF, .NS,and .NE) 

• Page headers and footers macros (.PH, .eh, .oh, .pf, .ef, 
and .OF) 
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• The . nr and . ds requests. 

9.2 Header and footer macros 

For header and footer macros ( . ph, . eh, . OH, . pf, . ef, and . OF) 
the argument [arg] is of the form 

" ' left-part' center-part' right-part' " 

If it is inconvenient to use an apostrophe (')as the delimiter because it 
occurs within one of the parts, it may be replaced uniformly by any 
other character. The . f c request redefines the delimiter. In formatted 
output, the parts are left justified, centered, and right justified, 
respectively. 

9.2.1 Page header 

The . PH macro specifies the header that is to appear at the top of every 
page. 

.PH [arg] 

The initial value is the default centered page number enclosed by 
hyphens. The page number contained in the P register is an Arabic 
number. The format of the number may be changed by the . af macro 
request. 

If debug mode is set using the flag option -rDl on the command line, 
additional information printed at the top left of each page is included in 
the default header. This consists of the Source Code Control System 
(SCCS) release and level of Memorandum Macros (thus identifying the 
current version followed by the current line number within the current 
input file), (See "Parameters Set From Command Line" and "SCCS 
Release Identification,") 

9.2.2 Even-page header 

The . EH macro supplies a line to be printed at the top of each even- 
numbered page immediately following the header. 

.EH [arg] 

Initial value is a blank line. 

9.2.3 Odd-page header 

The . OH macro is the same as the .EH except that it applies to odd- 
numbered pages. 
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.OH [arg] 

9.2.4 Page footer 

The . PF macro specifies a line that is to appear at the bottom of each 
page. 

.PF [arg] 

Its initial value is a blank line. If the -rCn flag option is specified on 
the command line, the type of copy follows the footer on a separate 
line. In particular, if -rC3 or -rC4 (DRAFT) is specified, the footer 
is initiahzed to contain the date instead of being a blank line. 

9.2.5 Even-page footer 

The . EF macro supplies a line to be printed at the bottom of each 
even-numbered page immediately preceding the footer. 

.EF [arg] 

Initial value is a blank line. 

9.2.6 Odd-page footer 

The . OF macro supplies a line to be printed at the bottom of each odd- 
numbered page immediately preceding the footer. 

.OF [arg] 

Initial value is a blank line. 

9.2.7 First page footer 

By default, the first page footer is a blank fine. If, in the input text file, 
the user specifies . PF, . of, or both, before the end of the first page of 
the document, these lines will appear at the bottom of the first page. 

The header, whatever its contents, replaces the footer on the first page 
only if the -rNl flag option is specified on the command line (see 
"Parameters Set From Command Line"). 

9.3 Default header and footer with section-page 
numbering 

Pages can be numbered sequentially within sections by section number 
and page number (see "First-Level Headings and Page- Numbering 
Style"). To obtain this numbering style, -rN3 or -rN5 is specified on 
the command line. In this case, the default footer is a centered section- 
page number, for example, 7-2; and the default page header is blank. 
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9.4 Strings and registers in lieader and footer macros 

String and register names can be placed in arguments to header and 
footer macros. If the value of the string or register is to be computed 
when the respective header or footer is printed, invocation must be 
escaped by four backslashes. This is because string or register 
invocation will be processed three times: 

1 . As the argument to the header or footer macro 

2. In a formatting request within the header or footer macro 

3 . In a . 1 1 request during header or footer processing 

For example, page number register p must be escaped with four 
backslashes in order to specify a header in which the page number is to 
be printed at the right margin: 

.PH '"'''Page \\\\nP"' 

creates a right-justified header containing the word "Page" followed 
by the page number. Similarly, to specify a footer with the section- 
page style, the user specifies 

,PF "ffA_ \\\\n(Hl-\\\\nP -'" 

If the user arranges for the string a ] to contain the current section 
heading that is to be printed at the bottom of each page, the . PF macro 
call would be 

.PF "''''\\\\*(a] ''" 

If only one or two backslashes were used, the footer would print a 
constant value for a ] , namely, its value when . PF appeared in the 
input text. 

9.5 Header and footer example 

The following sequence specifies blank lines for header and footer 
lines, page numbers on the outside margin of each page (that is, top left 
margin of even pages and top right margin of odd pages), and 
' 'Revision 3" on the top inside margin of each page. Nothing is 
specified for the center. 
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.PH "" 

.PF "" 

.EH "'\\\\nP' 'Revision 3'" 

.OH "'Revision 3''\\\\nP'" 

9.6 Generalized top-of-page processing 

Note: This part is intended only for users accustomed to 
writing formatter macros. 

During header processing, iran invokes two user-definable macros: 

• The . TP (top-of-page) macro is invoked in the environment 
(refer to . ev request) of the header, 

• The . PX is a page header user-exit macro that is invoked 
(without arguments) when the normal environment has been 
restored and with the no-space mode already in effect. 

The effective initial definition of . TP (after the first page of a 
document) is 

.de TP 

. sp 3 

.tl \\*(}t 

.if e 'tl \\*(}e 

.if o 'tl \\*(}o 

.sp 2 



The string } t contains the header, the string } e contains the even-page 
header, and the string } o contains the odd-page header as defined by 
the .PH, .EH, and . OH macros, respectively. To obtain more 
specialized page titles, the user may redefine the . TP macro to cause 
the desired header processing (see "Column Headings for Two- 
Column Output"). Formatting done within the . TP macro is 
processed in an environment different from that of the body. For 
example, to obtain a page header that includes three centered lines of 
data, that is, document number, issue date, and revision date, the user 
could define the . tp macro as follows: 
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.de TP 

.sp 

. ce 3 / 

777-888-999 \ 

Iss. 2, AUG 1977 

Rev. 7, SEP 1977 

• sp 

The . PX macro can be used to provide text that is to appear at the top 
of each page after the normal header and that can have tab stops to 
align it with columns of text in the body of the document. 

9.7 Generalized bottom-of-page processing 

Lines of text that are specified between the . BS (bottom-block start) 
and . BE (bottom-block end) macros will be printed at the bottom of 
each page after the footnotes (if any) but before the page footer. 

.BS 

zero or more lines of text 

.BE ^ 

This block of text is removed by specifying an empty block, that is, 

.BS 
.BE 

The bottom block will appear on the table of contents, pages, and the 
cover sheet for memorandum for file, but not on the technical 
memorandum or released-paper cover sheets. 

9.8 Top and bottom margins 

The . VM (vertical margin) macro allows the user to specify additional 
space at the top and bottom of the page. 

.VM [top] [bottom] 

This space precedes the page header and follows the page footer. The 
. VM macro takes two unsealed arguments that are treated as vertical 
spaces (v). For example, 

.VM 10 15 ^ 

adds 10 vertical spaces to the default top of page margin and 15 
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vertical spaces to the default bottom of page margin. Both arguments 
must be positive (default spacing at the top of the page may be 
decreased by redefining .tp). 

9.9 Proprietary marking macro 

The . PM (proprietary marking) macro appends a proprietary disclaimer 
to the page footer. The proprietary disclaimers are constructed from 
strings defined in the file /usr/lib/macros/strings .mm. 

.PM [code] 

The argument is selected from among the following: 

PMl 

PM2 or CA 

PM3 or CP 

PM4 
PM5 
PM6 

Use . PM at the beginning of your document, before you use footnotes 
or macros that define the memorandum style. Otherwise, an interaction 
between this macro and another that redefines the appearance of the 
bottom of the page may cause you problems. 

The default disclaimers are in a form approved for use by AT&T. 
Markings are underlined. (They are italicized in trof f .) 

System administrators can change the contents of the string .mm file 
to match your needs. This file is described in "Define File 
Information." In cases where the disclaimer message for a code 
argument has been removed, the argument issues a currently approved 
disclaimer message. Because the code argument may produce a shorter 
or longer disclaimer message, the page formatting of the document 
may be affected. 

9.1 Private documents 

.nr Pv value 

The word "PRIVATE" may be printed, centered, and underUned on 
the second line of a document (preceding the page header). This is 
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done by setting the Pv register value: 

do not print PRIVATE (default) 

1 PRIVATE on first page only 

2 PRIVATE on all pages 

If value is 2, the user definable . tp macro may not be used because 
the . TP macro is used by mm to print ' 'PRIVATE" on all pages except 
the first page of a memorandum on which . tp is not invoked. 

10. Table of contents and cover sheet 

The table of contents and the cover sheet for a document are produced 
by invoking the .TCand .CS macros, respectively. 

Note: This section refers to cover sheets for technical 
memoranda and released papers only. The mechanism for 
producing a memorandum for file cover sheet was discussed 
earlier (see "Abstract"). 

These macros normally appear once at the end of the document, after 
the Signature Block and Notations macros, and may occur in either 
order. (See "Signature Block," "Copy To and Other Notations.") 

The table of contents is produced at the end of the document because 
the entire document must be processed before the table of contents can 
be generated. Similarly, the cover sheet may not be desired by a user 
and is therefore produced at the end. 

1 0.1 Table of contents 

The . TC macro generates a table of contents containing heading levels 
that were saved for the table of contents as determined by the value of 
the CI register (see "Headings and Table of Contents"). 

.TC [slevel] [spacing] [tlevel] [tab] [headl] [head!] [headS] [head4] [headS] 

Arguments to . TC control spacing before each entry, placement of 
associated page number, and additional text on the first page of the 
table of contents before the word "CONTENTS". 

Spacing before each entry is controlled by the first and second 
arguments {slevel and spacing). Headings whose level is less than or 
equal to slevel will have spacing blank lines (nrof f ) or half- vertical 
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spaces (trof f) before them. Both slevel and spacing default to 1. 
This means that first-level headings are preceded by one blank line 
(nrof f ) or one-half a vertical space (t rof f ). The slevel argument 
does not control what levels of heading have been saved; saving of 
headings is the function of the CI register. 

The third and fourth arguments {tlevel and tab) control placement of 
the associated page number for each heading. Page numbers can be 
justified at the right margin with either blanks or dots, called leaders, 
separating the heading text from the page number, or the page numbers 
can follow the heading text. 

For headings whose level is less than or equal to tlevel (default 2), page 
numbers are justified at the right margin. In this case, the value of tab 
determines the character used to separate heading text from page 
number. If tab is (default value), dots (leaders) are used. If tab is 
greater than 0, spaces are used. 

For headings whose level is greater than tlevel, page numbers are 
separated from heading text by two spaces (that is, page numbers are 
ragged right, not right justified). 

Additional arguments {headl . . . head5) are horizontally centered on 
the page and precede the table of contents. 

If the . TC macro is invoked with at most four arguments, the user-exit 
macro . TX is invoked (without arguments) before the word 
' 'CONTENTS ' ' is printed or the user-exit macro . T Y is invoked and 
the word "CONTENTS" is not printed. 

By defining . TX or . ty and invoking . TC with at most four 
arguments, the user can specify what needs to be done at the top of the 
first page of the table of contents. For example. 
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.de TX 

• ce 2 

Special Application 

Message Transmission 

.sp 

.in +10n 

Approved : \ 1 ' 3 i ' 

• in 
.sp 

.TC 

yields the following output when the file is formatted. 

Special Application 
Message Transmission 

Approved: 



CONTENTS 



If the . TX macro were defined as . TY, the word "CONTENTS" 
would be suppressed. Defining . TY as an empty macro will suppress 
"CONTENTS" with no replacement: 

.de TY 

By default, the first-level headings will appear in the table of contents 
left justified. Subsequent levels will be aligned with the text of 
headings at the preceding level. These indentations can be changed by 
defining the Ci string, which takes a maximum of seven arguments 
corresponding to the heading levels. It must be given at least as many 
arguments as are set by the CI register. Arguments must be scaled. 
For example, with CI = 5 

.ds Ci .25i .5i .75i li li \"troff 

or 
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.ds Ci 2n 4n 6n 8n \"nroff 

Two other registers are available to modify the format of the table of 
contents — Oc and Cp. 

By default, table of contents pages will have lowercase roman numeral 
page numbering. If the Oc register is set to 1, the . TC macro will not 
print any page number but will instead reset the P register to 1. It is the 
user's responsibility to give an appropriate page footer to specify the 
placement of the page number. Ordinarily, the same . pf macro (page 
footer) used in the body of the document will be adequate. 

The list of figures, tables, exhibits and equations will be produced as 
separate pages unless Cp is set to 1, which causes these lists to appear 
on the same page as the table of contents. 

10.2 Cover Sheet 

The . CS macro generates a cover sheet in either the released paper or 
technical memorandum style (see "Abstract" for details of the 
memorandum for file cover sheet). 

• CS [pages] [other] [total] [figs] [tbls] [refs] 

All other information for the cover sheet is obtained from data given 
before the .mt macro call (see "Sequence of Beginning Macros"). If 
the technical memorandum style is used, the . CS macro generates the 
' 'Cover Sheet for Technical Memorandum." The data that appear in 
the lower left comer of the technical memorandum cover sheet (counts 
of: pages of text, other pages, total pages, figures, tables, and 
references) are generated automatically (0 is used for other pages). 
These values can be changed by supplying the corresponding 
arguments to the . CS macro. If the released-paper style is used, all 
arguments to . CS are ignored. 

11. References 

There are two macros ( . RS and . rf) that delimit the text of 
references, a string that automatically numbers the subsequent 
references, and an optional macro ( . rp) that produces reference pages 
within the document. 
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11.1 Automatic numbering of references 

Automatically numbered references can be obtained by typing \ * { Rf 

(invoking the string Rf ) immediately after the text to be referenced. ^ 

This places the next sequential reference number (in a smaller point \ 

size) enclosed in brackets one-half line above the text to be referenced. 

Reference count is kept in the Rf number register. 

11.2 Dei imiting reference text 

The . RS and . rf macros are used to delimit text of each reference. 

.RS [string-name] 

.RF 

For example, 

A line of text to be referenced. \* (Rf 

.RS 

reference text 

.RF 

11.3 Subsequent references 

The . RS macro takes one argument, a string-name. For example, , 

.RS aA 
reference text 

.RF 

The string aA is assigned the current reference number. This string 
may be used later in the document as the string call, \ * ( aA, to 
reference text which must be labeled with a prior reference number. 
The reference is output enclosed in brackets one-half line above the 
text to be referenced. No . RS/. rf pair is needed for subsequent 
references. 

11.4 Reference page 

The . RP macro causes a reference page, entitled by default 
"References," to be generated automatically at the end of the 
document (before table of contents and cover sheet) and to be listed in 
the table of contents. 

.RP [argl] [arg2] 

This page contains the reference items enclosed within . RS/ . RF pairs. 
Reference items will be separated by a space (nrof f ) or one-half a 
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vertical space (trof f ) unless the Ls register is set to to suppress 
this spacing. The user may change the reference page title by defining 
the Rp string: 

.ds Rp "New Title" 

The . RP (reference page) macro may be used to produce reference 
pages anywhere else within a document (that is, after each major 
section). It is not needed to produce a separate reference page with 
default spacings at the end of the document. 

Two . RP macro arguments allow the user to control resetting of 
reference numbering and page skipping. 

arg1 Meaning 

reset reference counter (default) 

1 do not reset reference counter 

arg2 Meaning 

put on separate page (default) 

1 do not cause a following . SK 

2 do not cause a preceding . SK 

3 no .SK before or after 

If no . SK macro is issued by the . RP macro, a single blank line will 
separate the references from the following and preceding text. The 
user may wish to adjust spacing. For example, to produce references at 
the end of each major section: 

.sp 3 

.RP 1 2 

.H 1 "Next Section" 

12. Miscellaneous features 

12.1 Bold, italic, and roman fonts 

When called without arguments, the . B macro changes the font to bold 
and the . I macro changes to underlining (nrof f) or italic (trof f ). 
This condition continues until the occurrence of the . R macro which 
causes the roman font to be restored. 
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B [bold-arg] [previous-font-arg] 
I [italic-arg] [previous-font-arg] 
R 



Thus, 

.1 

here is some text . 

.R 

yields underlined text via nrof f (1) and italic text via t rof f (1). 

If the . B or .1 macro is called with one argument, that argument is 
printed in the appropriate font (underlined in the nrof f formatter for 
. I). Then the previous font is restored; underlining is turned off in the 
nrof f formatter. If two or more arguments (maximum six) are given 
with a . B or . I macro call, the second argument is concatenated to the 
first with no intervening space (1/12 space if the first font is italic) but 
is printed in the previous font. Remaining pairs of arguments are 
similarly alternated. For example, 

. I one " two " three -four 

produces 

one two three -four 

The . B and . I macros alternate with the prevailing font at the time the 
macros are invoked. To alternate specific pairs of fonts, the following 
macros are available: 

. IB italic bold 
.Bi bold italic 
. IR italic roman 
. RI roman italic 
.RB roman bold 
,BR bold roman 

Each macro takes a maximum of six arguments and alternates 
arguments between specified fonts. 

When using a terminal that cannot underline, the following can be 
inserted at the beginning of the document to eliminate all underlining: 
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. rm ul 
.rm cu 

Note: Font changes in headings are handled separately (see 
"Control by Level"). 

12.2 Justification of right margin 

The . SA macro is used to set right-margin justification for the main 
body of text. 

.SA {arg\ 

Two justification flags are used — current and default. Initially, both 
flags are set for no justification in the nrof f formatter and for 
justification in the trof f formatter. The argument causes the 
following action: 

Sets both flags to no justification, the same as the 
. na request. 

1 Sets both flags to cause both right and left 
justification, the same as the . ad request, 

omitted Causes the current flag to be copied from the default 
flag, thus performing either a . na or .ad depending 
on the default condition. 

In general, the no adjust request ( . na) can be used to ensure that 
justification is turned off, but . SA should be used to restore 
justification, rather than the . ad request. In this way, justification or 
no justification for the remainder of the text is specified by inserting 
. SA or . SA 1 once at the beginning of the document. 

12.3 sees reiease identification 

The RE string contains the SCCS release and the Memorandum Macros 
text formatting package current version level. For example, 

This is version \* (RE of the macros. 

produces 

This is version 10.129 of the macros. 
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This information is useful in analyzing suspected bugs in mm. The 
easiest way to have the release identification number appear in the 
output is to specify -rDl (see "Parameters Set From Command 
Line") on the command line. This causes the RE string to be generated 
as part of the page header (see ' 'Page Header' '). 

12.4 Two-column output 

The . 2C macro begins 2-column processing which continues until a 
. IC macro (1-column processing) is encountered. 

.2C 

text and formatting requests (except another . 2C) 

.IC 

In 2-column processing, each physical page is thought of as containing 
2-columnar "pages" of equal (but smaller) "page" width. Page 
headers and footers are not affected by 2-column processing. The . 2C 
macro does not balance 2-column output. 

It is possible to have full-page width footnotes and displays when in 2- 
column mode, although default action is for footnotes and displays to 
be narrow in 2-column mode and wide in 1-column mode. Footnote 
and display width is controlled by the . wc (width control) macro, 
which takes the following arguments: 

arg Meaning 

N Default mode (-WF, -ff, -wd, fb). 

WF Wide footnotes (even in 2-column mode). 

-WF DEFAULT: Tum off WF. Footnotes follow column mode; 

wide in 1-column mode (IC), narrow in 2-column mode 
(2C), unless FF is set. 

FF First footnote. All footnotes have same width as first 

footnote encountered for that page. 

-FF DEFAULT: Tum off FF. Footnote style follows settings 

of WFor -WF. 

WD Wide displays (even in 2-column mode). 

-WD DEFAULT: Displays follow the column mode in effect 

when display is encountered. 
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FB DEFAULT: Floating displays cause a break when output 

on the current page. 

-FB Floating displays on current page do not cause a break. 

Note: The . WC WD FF command will cause all displays to be 
wide and all footnotes on a page to be the same width while 
. WC N will reinstate default actions. If conflicting settings are 
given to . WC, the last one is used. A , WC WF -WF command 
has the effect of a . WC -WF. 



12.5 Column headings for two-column output 

Note: This section is intended only for users accustomed to 
writing formatter macros. 

In 2-column processing output, it is sometimes necessary to have 
headers over each column, as well as headers over the entire page. 
This is accomplished by redefining the . TP macro to provide header 
lines both for the entire page and for each of the columns. For 
example, 

.de TP 

.sp 2 

.tl 'Page \\nP' OVERALL' ' 

.tl "TITLE" 

.sp 

• nf 

.ta 16C 31R 34 50C 65R 

left"Icenter''Iright''Ileft "Icenter'Iright 
"Ifirst column" I "I "I second column 
.fi 

• sp 2 

where " I stands for the tab character. 

The above example will produce two lines of page header text plus two 
lines of headers over each column. Tab stops are for a 65-en overall 
line length. See "Generalized Top-of-Page Processing" for more 
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information on headers. 

12.6 Vertical spacing 

.SP [lines] 

There are several ways of obtaining vertical spacing, all with different 
effects. The . sp request spaces the number of lines specified unless 
the no space ( . ns) mode is on, in which case the . sp request is 
ignored. The no space mode is set at the end of a page header to 
eliminate spacing by a . sp or . bp request that happens to occur at the 
top of a page. This mode can be turned off by the , r s (restore 
spacing) request. 

The . SP macro is used to avoid the accumulation of vertical space by 
successive macro calls. Several . SP calls in a row will not produce 
the sum of the arguments but only the maximum argument. For 
example, the following produces only three blank fines: 

.SP 2 
.SP 3 
.SP / 

Many Memorandum Macros use . SP for spacing. For example, . LE 
1 (see "List-Item Macro") immediately foUowed by . P (see 
"Paragraphs") produces only a single blank line (nrof f ) or one-half 
a vertical space (trof f ) between the end of the list and the following 
paragraph. An omitted argument defaults to one blank line (nrof f ) or 
one vertical space (t rof f ). Negative arguments are not permitted. 
The argument must be unsealed, but fractional amounts are permitted. 
The . SP macro (as well as . sp) is also inhibited by the . ns (no 
space) request. 

12.7 Skipping pages 

The . SK macro skips pages but retains the usual header and footer 
processing. 

.SK [pages] 

If the pages argument is omitted, nuU, or 0, . SK skips to the top of the 

next page unless it is currently at the top of a page (in which case it * 

does nothing). A . SK n command skips n pages. A .SK positions text 

that follows it at the top of a page, while . SK 1 leaves one page blank 
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except for the header and footer. 

12.8 Forcing an odd page 

The . OP macro is used to ensure that formatted output text following 
the macro begins at the top of an odd-numbered page. 

.OP 

• If currently at the top of an odd-numbered page, text output 
begins on that page (no motion takes place). 

• If currently on an even page, text resumes printing at the top of 
the next page. 

• If currently on an odd page (but not at the top of the page), one 
blank page is produced, and printing resumes on the next odd- 
numbered page after that. 

12.9 Setting point size and verticai spacing 

The prevailing point size and vertical spacing can be changed by 
invoking the . S macro. 

. S [point size] [vertical spacing] 

In the trof f formatter, the default point size obtained from the mm 
register S is 10 points; the vertical spacing is 12 points, six lines per 
inch. The mnemonics D (default value), C (current value), and P 
(previous value) can be used for both arguments. See "Parameters Set 
From Command Line" for an alternative way to set these parameters. 

• If an argument is negative, current value is decremented by the 
specified amount. 

• If an argument is positive, current value is incremented by the 
specified amount. 

• If an argument is unsigned, it is used as the new value. 

• If there are no arguments, the . S macro defaults to P. 

• If the first argument is specified but the second is not, then D, the 
default, is used for the vertical spacing. 

Default value for vertical spacing is always two points greater than the 
current point size. Footnotes are two points smaller than the body with 
an additional 3 -point space between footnotes. A null (" ") value for 
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.s 


p p 


.s 


C n 


.s 


n C 


.s 


n D 


• S 


C D 


.s 


C C 


.s 


nn 



either argument defaults to C, the current value. Thus, if n is a numeric 
value: 

.s 

.S "" n 

.S n "" 

.S n 

.S "" = 

.S nn = 

If the first argument is greater than 99, the default point size, 10 points, 
is restored. If the second argument is greater than 99, the default 
vertical spacing (current point size plus two points) is used. For 
example, 

.S 100 = .S 10 12 

.S 14 111 = .S 14 16 

12.10 Reducing point size of a string 

The . SM macro allows the user to reduce by one point the size of a 
string. 

. SM stringl [string!'] [stringS] 

If the third argument (stringS) is omitted, the first argument (stringl) is 
made smaller and is concatenated with the second argument {string!) if 
specified. If all three arguments are present (even if any are null), the 
second argument is made smaller and all three arguments are 
concatenated. For example, 

.SM X 
produces 
X 
.SM Y XYX "" 

produces 

YXYX 
and 
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.SM ( YXYX ) 

produces 
(YXYX) 

12.11 Producing accents 

Strings can be used to produce accents for letters as shown in the 
following examples: 

Input Output 

Grave accent c\*^ c 

Acute accent e \ * ' e' 

Circumflex oX*" o 

Tilde n\*~ n 

Cedilla c\*, 9 

Lower case umlaut u\ * : ii 

Upper case umlaut U\ * ; U 

12.12 Inserting text interactively 

,RD [prompt] [diversion] [string] 

The . RD (read insertion) macro allows a user to stop the standard 
output of a document and to read text from the standard input until two 
consecutive newline characters are found. When newline characters 
are encountered, normal output is resumed. 

• The prompt argument will be printed at the terminal. If not 
given, . RD signals the user with a BEL on terminal output. 

• The diversion argument allows the user to save all text typed in 
after die prompt in a macro whose name is that of the diversion. 

• The string argument allows the user to save for later reference 
the first line following the prompt in the named string. 

The . RD macro follows the formatting conventions in effect. Thus, the 
following examples assume that the . RD is invoked in no-fill mode 

(.nf): 
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.RD Name aA bB 

produces 

Name: S. Jones (user types name) 

16 Elm Rd., 

Piscataway 

The diverted macro . aA will contain 

S. Jones 
16 Elm Rd.. 
Piscataway 

The string bB (\ * (bB) contains "S. Jones". 

A newline character followed by an eo/ (user-specifiable end-of-file 
character) also allows the user to resume normal output. See stty(l) 
in AlUX Command Reference for information about the user-specifiable 
sequences. 

13. Errors and debugging 

13.1 Error terminations 

When a macro detects an error, the following actions occur: 

• A break occurs. 

• The formatter output buffer (which may contain some text) is 
printed to avoid confusion regarding location of the error. 

• A short message is printed giving the name of the macro that 
detected the error, type of error, and approximate Une number in 
the current input file of the last processed input fine. Error 
messages are explained in "Error Messages." 

• Processing terminates unless register D has a positive value. In 
the latter case, processing continues even though the output is 
guaranteed to be deranged from that point on. (See "Parameters 
Set From Command Line.") 

The error message is printed by generating the message directly to the 
user terminal. If an output filter, such as 3 0(1), 4 50(1), or hp(l) is 
being used to post-process the nrof f formatter output, the message 
may be garbled by being mixed with text held in that filter's output 
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buffer. 

Note: If any of cw(l), eqn/neqn(l), and tbl(l) programs are 
being used and if the -olist flag option of the formatter causes 
the last page of the document not to be printed, a harmless 
"broken pipe" message may result. 

13.2 Disappearance Of output 

Disappearance of output usually occurs because of an unclosed 
diversion (for example, a missing . DE or . FE macro). Fortunately, 
macros that use diversions are careful about it, and these macros check 
to make sure that illegal nestings do not occur. If any error message is 
issued concerning a missing . DE or . FE, the appropriate action is to 
search backwards from the termination point looking for the 
corresponding associated .DF, .DS,or .FS (because these macros are 
used in pairs). 

The following command: 

grep -n ' "X . [EDFRT] [EFNQS] ' filename 1 jilename2 
prints all the .DF, .DS, .DE, .EQ, .EN, .FS, .FE, .RS, .RF, .TS, 

and . TE macros found in filenamel and filename!. Each is preceded 
by its filename and the line number in that file. This listing can be used 
to check for illegal nesting, omission of these macros, or both. 

14. Extending and modifying memorandum 
macros 

14.1 Naming conventions 

In this part, the following conventions are used to describe names: 

n: Digit 

a: Lowercase letter 

A: Uppercase letter 

x: Any alphanumeric character (n, a, or A, that is, letter or 

digit) 
s: Any nonalphanumeric character (special character) 

All other characters are literals, that is, they are characters that stand 
for themselves. 
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Request, macro, and string names are kept by the formatters in a single 
internal table; therefore, there must be no duplication among such 
names. Number register names are kept in a separate table. 

1 4.1 .1 Names used by formatters 

requests: aa (most common) 

an (only one, currently: c2) 
registers: aa (normal) 

.jc (normal) 

. J (only one, currently: .) 

a . (only one, currently: c . ) 

% (page number) 

14.1.2 Names used by memorandum macros 

macros and strings: 

A, AA, Aa (accessible to users; for example, macros P and 
HU, strings F, BU, and Lt) 

nA (accessible to users; only two, currently: IC and 2C) 

aA (accessible to users; only one, currently: nP) 

s (accessible to users; only the seven accents, currently. 
(See "Reducing Point Size of a String.") 

)x, }x, ]x, >x, Ix (internal) 

registers: An, Aa (accessible to users; for example. Hi, Fg) 

A (accessible to users; meant to be set on the command line; 
for example, C) 

:x, ;x, ^x, ?jc, \x (internal) 

14.1 .3 Names used by cw, eqn/neqn, and tbi 

The cw(l) program is the constant- width font preprocessor for the 
t rof f formatter. It uses the following five macro names: 

.CD .CN .CP .CW .PC 
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This preprocessor also uses the number register names cE and cw. 
Mathematical equation preprocessors, eqn(l) and neqn(l), use 
registers and string names of the form nn. The table preprocessor, 
tbl(l), uses T&, T#, and TW, and names of the form: 

a- a+ a \ nn na "a #a §s 

14.1 .4 Names defined by user 

Names that consist either of a single lowercase letter or a lowercase 
letter followed by a character other than a lowercase letter (names . c2 
and . nP are already used) should be used to avoid duplication with 
already used names. The following is a possible naming convention: 

macros: oA (for example, bG, kw) 

strings: as (for example, c ) , f ] , p } ) 

registers: a (for example, f , t) 

14.2 Sample extensions 

14.2.1 Appendix headings 

The following is a way of generating and numbering appendix 
headings: 

.nr Hu 1 

.nr a 

.de aH 

,nr a +1 

.nr P 

.PH ""'''Appendix Wna-WWWWnP' " 

• SK 

.HU "\\1" 

After the above initialization and dej&nition, each call of the form 

.aH "title" 

begins a new page, with the page header changed to "Appendix a-n", 
and generates an unnumbered heading of title, which can be saved for 
the table of contents. To center appendix titles the He register must be 
set to 1 (see "Centered Headings"). 
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14.2.2 Hanging indent with tabs 

The following example illustrates the use of the hanging indent feature 
of variable-item lists (see "Variable-Item List"). A user-defined 
macro is defined to accept four arguments that make up the mark. In 
the output, each argument is to be separated from the previous one by a 
tab; tab settings are defined later. Since the first argument may begin 
with a period or apostrophe, the \ & is used so that the formatter will 
not interpret such a line as a formatter request or macro call. 

Note: The 2-character sequence \& is understood by formatters 
to be a * 'zero- width" space. It causes no output characters to 
appear, but it removes the special meaning of a leading period 
or apostrophe. 

The \t is translated by the formatter into a tab. The \c is used to 
concatenate the input text that follows the macro call to the line built by 
the macro. The user-defined macro and an example of its use are 

• de aX 

.LI 

\&\\$l\t\\$2\t\\$3\t\\$4\t\c 



.ta .5i li 1.5i 2i 
.VL 2 9 

.aX .nh off \- no 
No hyphenation. 

Automatic hyphenation is turned off. 
Words containing hyphens 

(for example, mother-in-law) can still be 
split across lines. 
.aX .hy on \- no 
Hyphenate . 

Automatic hyphenation is turned on. 
. aX .hc\ c none none no 

Hyphenation indicator character is set to ^ ''c'' ' 
or removed. 
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During text processing, the indicator is 
suppressed and will not appear in the output , 
Prefixing the indicator to a word has the 
effect of preventing hyphenation of that word. 
.LE 

Note that the space following " . hc\ " is required. 

The resulting output is 



nh off 



hy on 



he c 



none 



no No hyphenation. Automatic 

hyphenation is turned off. Words 
containing hyphens (for example, 
mother-in-law) may still be split 
across lines. 

no Hyphenate. Automatic 

hyphenation is turned on. 

none Hyphenation indicator character is 
set to c or removed. During text 
processing, the indicator is 
suppressed and will not appear in 
the output. Prefixing the indicator 
to a word has the effect of 
preventing hyphenation of that 
word. 



15. Summary 

The following are qualities of mm that have been emphasized in its 
design in approximate order of importance: 

• Robustness in the face of error — A user need not be an 
nrof f/trof f expert to use the Memorandum Macros. When 
the input is incorrect, either the macros attempt to make a 
reasonable interpretation of the error or an error message 
describing the error is produced. An effort has been made to 
minimize the possibility that a user will get cryptic system 
messages or strange output as a result of simple errors. 

• Ease of use for simple documents — It is not necessary to write 
complex sequences of commands to produce documents. 
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Reasonable macro argument default values are provided where 
possible. 

• Setting parameters — There are many different preferences in 
the area of document styling. Many parameters are provided so 
that users can adapt input text files to produce documents that 
meet their respective needs with a wide range of styles. 

• Extension by moderately expert users — A strong effort has been 
made to use mnemonic naming conventions and consistent 
techniques in construction of macros. Naming conventions are 
given so that a user can add new macros or redefine existing ones 
if necessary. 

• Device independence — A common use of inm is to produce 
documents on hard copy via teletypewriter terminals using the 
nrof f formatter. Macros can be used conveniently with both 
10- and 12-pitch terminals. In addition, output can be displayed 
on an appropriate CRT terminal. Macros have been constructed 
to allow compatibility with thetroff(l) formatter so that 
output can be produced on both a phototypesetter and a 
teletypewriter/CRT terminal. 

• Minimization of input — The design of macros attempts to 
minimize repetitive typing. For example, if a user wants to have 
a blank line after all first- or second-level headings, the user need 
only set a specific parameter once at the beginning of a document 
rather than type a blank line after each such heading. 

• Uncoupling of input format from output style — There is but one 
way to prepare the input text although the user may obtain a 
number of output styles by setting a few global flags. For 
example, the . H macro is used for all numbered headings, yet the 
actual output style of these headings can be made to vary from 
document to document or within a single document. 

1 6. mm Examples and reference tables 

This section contains an example of an input file of a simple letter that 
is also shown formatted by both nrof f and trof f using the 
Memorandum Macros. This example illustrates how the formatters 
work and what to expect from your input file. 
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There are also four tables in this section that are useful reference tools 
when using the Memorandum Macros. The tables are 

Macro Names: This table is an alphabetic summary of all the 

Memorandum Macro names available for 
producing a document. 

String Names: This table is a summary of all the predefined 

string names in the Memorandum Macro 
package. 

Number Register Names: 

This table is a summary of all the predefined 
number register names in the Memorandum 
Macro package. 

Error Messages: This table is a list of error messages that you 
may encounter when formatting a document. 
Memorandum Macro error messages as well 
as nrof f/trof f error messages are 
explained. 
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Figure 4-1. Example of a simple letter - input file 
INPUT: 

.nr N 2 \" specifies header to be omitted from page 1 

.ta 3i 

September 5, 1987 

.SP 2 

Mr. Steven J. Jones 

.br 

386 Broderick Street 

-br 

San Francisco, CA 94111 

.SP 

Dear Mr. Jones: 

.P 

Enclosed please find a copy of 

.1 

A/UX\*F Text Processing Tools. 

.R 

.FS 

A/UX is a trademark of Apple Computer, Inc. 

.FE 

.P 

This manual covers using the 

\s-lUNIX\s+l\*F 

.FS 

\s-lUNIX\s+l is a registered trademark of AT&T Information 

Systems . 

.FE 

operating system for preparing documentation, and includes 

topics such as: 

.VL 17 

.LI Formatters: 

the \fBnroff/troff\fR formatters, 

with tables listing defaults and explanations of all requests 

.LI Tables: 

the \fBtbl\fR program, 

with examples of code at the end of the chapter 

.LI Equations: 

the \fBeqn\fR program, for printing mathematical expressions 

.LI "Macro\ Package:" 

the \fBmm\fR macro package chapter gives a complete outline of 

all the capabilities of this powerful document processing tool 

.LE 

.P 

I hope you will find this guide useful in preparing your report, 

.SP 

.nf 

Sincerely, 

.SP 2 

Rosemary Clooney 

Documentation Specialist 

RC/dcb 

Enc. 

.fi 
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Figure 4-2. Example of a simple letter - nrof f output 

nroff OUTPUT: September 5, 1987 



Mr. Steven J. Jones 
386 Broderick Street 
San Francisco, CA 94111 

Dear Mr. Jones: 

Enclosed please find a copy of A/UX l Text Processing 
Tools . 

This manual covers using the UNIX2 operating system for 
preparing documentation, and includes topics such as: 

Formatters: the nroff/troff formatters, with tables 
listing defaults and explanations of all 
requests 

Tables: the tbl program, with examples of code at 
the end of the chapter 

Equations: the eqn program, for printing 
mathematical expressions 

Macro Package: the mm macro package chapter gives a 

complete outline of all the capabilities 
of this powerful document processing tool 

I hope you will find this guide useful in preparing your 
report . 

Sincerely, 



Rosemary Clooney 
Documentation Specialist 

RC/dcb 

Enc. 



1. A/UX is a trademark of Apple Computer, Inc. 

2. UNIX is a registered trademark of AT&T Information 
Systems. 
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Figure 4-3. Example of a simple letter - trof f output 
trof f OUTPUT: September 5, 1987 

Mr. Steven J. Jones 
386 Broderick Street 
San Francisco, C A 94111 

Dear Mr, Jones: 

Enclosed please find a copy of A/UX^ Text Processing Tools. 

This manual covers using the UNIX^ operating system for preparing 
documentation, and includes topics such as: 

Formatters: the nrolT/troff formatters, with tables listing 

defaults and explanations of all requests 

Tables: the tbl program, with examples of code at the end 

of the chapter 

Equations: the eqn program, for printing mathematical 

expressions 

Macro Package: the mm macro package chapter gives a complete 
outline of all the capabilities of this powerful 
document processing tool 

I hope you will find this guide useful in preparing your report. 

Sincerely, 

Rosemary Clooney 
Documentation Specialist 

RC/dcb 

Enc. 



1 . AAJX is a trademark of Apple Computer, Inc. 

2. UNIX is a registered trademark of AT&T Information Systems. 



4-1 08 A/UX Text Processing Tools 



16.1 Memorandum macro names 



Macro Description 



IC 1 -column processing 

.IC 

2C 2-column processing 

.2C 

AE Abstract end 

.AE 

AF Alternate format of ' 'Subject/Date/From' ' block 

.AF [company-name] 

AL Automatically incremented list start 

• AL [type] [text-indent] [1] 

AS Abstract start 

• AS [arg] [indent] 

AT Author's title 

. AT [title] . . . 

AU Author information 

,A\J name [initials] [loc] [dept] 
[ext] [room] [arg] [arg] [arg] 

AV Approval signature 

.AV [name] 

B Bold 

.B [bold-arg] [prev-font- 

arg] [bold] [prev] [bold] [prev] 

BE Bottom block end 

• BE 

Bi Bold/italic 

.BI [bold-arg] [italic- 

arg] [bold] [italic] [bold] [italic] 

BL Bullet list start 

.BL [text-indent] [1] 
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Macro 


Description 


BR 


Bold/roman 

.BR [bold-arg] [roman-arg] 
[bold] [roman] [bold] [roman] 


BS 


Bottom block start 

.BS 


CS 


Cover sheet 

.CS [pages] [other] [total] [figs] [tbls] [refs] 


DE 


Display end 

.DE 


DF 


Display floating start 

.DF [format] [fill] [right-indent] 


DL 


Dash list start 

.DL [text-indent] [1] 



DS Display static start 

.DS [format] [fill] [right-indent] 

EC Equation caption 

• EC [title] [override] [flag] 

EF Even-page footer 

.EF [arg] 

EH Even-page header 

-EH [arg] 

EN End equation display 

.EN 

EQ Equation display start 

• EQ [label] 

EX Exhibit caption 

• EX [title] [override] [flag] 

FC Formal closing 

-FC [closing] 
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Macro Description 

FD Footnote default format 

.FD [arg] [1] 

FE Footnote end 

.FE 

FG Figure title 

.FG [title] [override] [flag] 

FS Footnote start 

• FS [label] 

H Heading — numbered 

.H level [heading-text] [heading-suffix] 

HC Hyphenation character 

. HC [hyphenation-indicator] 

HM Heading mark style 

(arabic or roman numerals, or letters) 
.HM [argl]...[arg7] 

HU Heading — unnumbered 

.HU heading-text 

HX* Heading user exit X (before printing heading) 

.HX dlevel rlevel heading-text 

HY* Heading user exit Y (before printing heading) 

.HY dlevel rlevel heading-text 

HZ* Heading user exit Z (after printing heading) 

.HZ dlevel rlevel heading-text 



Macros marked with an asterisk are not, in general, called directly by the user. They 
are "user exits" defined by the user and called by mm from inside header, footer, or 
other macros. 
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Macro Description 

I Italic (underline in the nrof f formatter) 

. I [italic-arg] [prev-font- 
arg] [italic] [prev] [italic] [prev] 

I A Inside address start 

. I A [addressee-name] [title] 

IB Italic/bold 

. IB [italic-arg] [bold-arg] [italic] 
[bold] [italic] [bold] 

IE Inside address end 

.IE 

IR ItaUc/roman 

. IR [italic-arg] [roman-arg] [italic] 
[roman] [italic] [roman] 

LB List begin 

.LB text-indent mark-indent pad type [mark] 
[U-space] [LB-space] 

LC List-status clear 

.LC [list-level] 

LE List end 

.LE [1] 

LI List item 

.LI [mark] [1] 

LO Letter options 

.LO type [arg] 

LT Letter type 

.LT [arg] 

ML Marked list start 

.ML mark [text-indent] [1] 

MT Memorandum type 

,MT [type] [addressee] or .MT 4 1 
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Macro Description 

ND New date 

.ND new-date 

NE Notation end 

.NE 

NS Notation start 

• NS {arg\ 

nP Double-line indented paragraphs 

.nP 

OF Odd-page footer 

.OF [arg] 

OH Odd-page header 

.OH [arg} 

OK Other keywords for Technical Memo cover sheet 

. OK \_keyword\ . . . 

OP Odd page 

.OP 

p Paragraph 

.P {type} 

PF Page footer 

.PF {arg\ 

PH Page header 

.PH {arg\ 

PM Proprietary marking 

.PM [code] 
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Macro Description 

PX* Page-header user exit 

• PX 

R Return to regular (roman) font 

.R 

RB Roman/bold 

.RB [roman-arg] [bold-arg] [roman] [bold] 
[roman] [bold] 

RD Read insertion from terminal 

,RD [prompt] [diversion] [string] 

RF Reference end 

.RF 

Rl Roman/italic 

• RI [roman-arg] [italic- 

arg] [roman] [italic] [roman] [italic] 

RL Reference list start 

.RL [text-indent] [1] 

RP Produce reference page 

.RF [arg] [arg] 

RS Reference start 

.RS [string-name] 

S Settroff formatter point size and vertical 

spacing 
.S [size] [spacing] 



Macros marked with an asterisk are not, in general, called directly by the user. They 
are "user exits" defined by the user and called by mm from inside header, footer, or 
other macros. 
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Macro Description 

SA Set adjustment (right-margin justification) default 

.SA [arg] 

SG Signature line 

.SG [arg] [1] 

SK Skip pages 

• SK [pages] 

SM Make a string smaller 

. SM stringl [string!] [stringS] 

SP Space vertically 

• SP [lines] 

TB Table title 

.TB [title] [override] [flag] 

TC Table of contents 

.TC [slevel] [spacing] [tlevel] 
[tab] [headl] [head2] [headS] [head4] [headS] 

TE Table end 

• TE 

TH Table header 

.TH [N] 

TL Title of memorandum 

.TL [charging-case] [filing-case] 

TM Technical memorandum number(s) 

.TM [number] ... 

TP* Top-of-page macro 

.TP 



Macros marked with an asterisk are not, in general, called directly by the user. They 
are "user exits'* defined by the user and called by mm frcMn inside header, footer, or 
other macros. 
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Macro Description 

TS Table start 

.TS [H] 

TX* Table of contents user exit 

.TX 

TY* Table of contents user exit (suppress CONTENTS) 

.TY 

VL Variable-item list start 

.VL text-indent [mark-indent] [1] 

VM Vertical margins 

.VM [top] [bottom] 

WA Writer's address start 

.WA writer-name [title] 

wc Foomote and display width control 

.WC [format] 

wc Footnote and display width control 

.wc [format] 



Macros marked with an asterisk are not, in general, called directly by the user. They 
are "user exits" defined by the user and called by mm from inside header, footer, or 
other macros. 
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16.2 String names 



String Description 



BU Bullet (nroff: ©,troff: •) 

Ci Table of contents indent list 

Up to seven scaled arguments for heading levels 

DT Date (current date, unless overridden) 

Month, day, year (for example, May 1, 1988) 

EM Em dash string 

Produces an em dash in the trof f formatter and a 
double hyphen in nroff 

F Footnote number generator 

nroff: \u\\n+(:p\i 
t rof f : \v'-.4m'\s-3\\n+(:p\s0\v'.4m' 

HF Heading font list 

Up to seven codes for heading levels 1 through 7 
3 3 2 2 2 2 2 (levels 1 and 2 bold, 3 through 7 
underlined by nroff and italicized by trof f) 

HP Heading point size list 

Up to seven codes for heading levels 1 through 7 

Le Title for LIST OF EQUATIONS 

Lf Tide for LIST OF HGURES 

Lt Tide for LIST OF TABLES 

Lx Tide for LIST OF EXHIBITS 

RE sees Release and Level of Memorandum Macros 

Release.Level (for example, 15.129) 

Rf Reference number generator 

Rp Title for References 

Tm Trademark string 

Places ' 'TM" Vi line above text that it follows 
Seven accent strings are also available. 
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Note: If the released-paper style is used, then, in addition to the 
above strings, certain BTL location codes are defined as strings 
and are needed only until the . MT macro is called. The 
following codes are recognized: ak, al, alf, cb, CH, cp, dr, 

F J, HL, HO, HOH, HP, IH, IN, INH, IW, MH, MV, PY, RD, RR, 
WB, WH, and WV. 
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16.3 Number register names 



Register Description 



A * t Handles preprinted forms and Bell System logo 

0, [0:2] 

Au Inhibits printing of author information 

l.[0:l] 

C * t Copy type (original, DRAFT, etc.) 

(Original), [0:4] 

CI Level of headings saved for table of contents 

2, [0:7] 

Cp Placement of list of figures, etc. 

1 (on separate pages), [0:1] 

D * t Debug flag 

0,[0:1] 

De Display eject register for floating dislays 

0,[0:1] 

D f Display format register for floating displays 

5, [0:5] 

Ds Static display pre- and post-space 

1,[0:1] 

E * t Controls font of the Subject/Date/From fields 

l(nroff)0(troff), [0:1] 

EC Equation counter, used by . EC macro 

0, [0:?], incremented by one for each . EC call 



An asterisk attached to a register name indicates this register can be set only from the 
command line or before the macro definitions are read by the formatter. 

Section 1.3 has notes on setting and referencing registers. Any register having a 
single-character name can be set from the command line. 
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Register Description 



E j Page-ejection flag for headings 

(no eject), [0:7] 

Eq Equation label placement 

(right-adjusted), [0:1] 

Ex Exhibit counter, used by . EX macro 

0, [0:?], incremented by one for each . ex call 

Fg Figure counter, used by . FG macro 

0, [0:?], incremented by one for each . FG call 

Fs Footnote space (i.e., spacing between footnotes) 

1, [0:?] 

H1-H7 Heading counters for levels 1 through 7 

0, [0:?], incremented by the . H macro of corresponding 
level or the . HU macro if at level given by the Hu 
register. The H2 through H7 registers are reset to by 
any . H ( . HU) macro at a lower-numbered level. 

Hb Heading break level (after . H and . HU) 

2, [0:7] 

He Heading centering level for . H and . HU 

(no centered headings), [0:7] 

Hi Heading temporary indent (after . H and . HU) 

1 (indent as paragraph), [0:2] 

Hs Heading space level (after , H and . HU) 

2 (space only after . H 1 and . H 2), [0:7] 

Ht Heading type (for . H: single or concatenated numbers) 



* An asterisk attached to a register name indicates this register can be set only from the 
command liae or before the macro definitions are read by the formatter. 

t Section 1.3 has notes on setting and referencing registers. Any register having a 
single-character name can be set from the command line. 
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Register Description 



(concatenated numbers: 1.1.1, etc.), [0:1] 

Hu Heading level for unnumbered heading ( . HU) 

2 ( . HU at the same level as . H 2), [0:7] 

Hy Hyphenation control for body of document 

(automatic hyphenation off), [0:1] 

L * t Length of page 

66, [20:?] (Hi, [2i:?] in trof f formatter) 

Le List of equation 

(list not produced) [0:1] 

Lf List of figures 

1 (list produced) [0:1] 

Li List indent 

6(nroff)5(troff), [0:?] 

Ls List spacing between items by level 

6 (spacing between all levels) [0:6] 

Lt List of tables 

1 (list produced) [0:1] 

Lx List of exhibits 

1 (list produced) [0:1] 

N * t Numbering style 

0, [0:5] 

Np Numbering style for paragraphs 

(unnumbered) [0: 1] 



* An asterisk attached to a register name indicates this register can be set only from the 
command line or before the macro definitions are read by the formatter. 

t Section 1.3 has notes on setting and referencing registers. Any register having a 
single-character name can be set from the command line. 
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Register Description 



0*t Offset of page 

.751, [0:?] (0.5i, [Oi:?] in trof f formatter) 
For nrof f formatter, these values are unsealed 
numbers representing lines or character positions. 
For trof f formatter, these values must be scaled. 

Oc Table of contents page numbering style 

(lowercase Roman), [0:1] 

Of Figure caption style 

(period separator), [0:1] 

Pt Page number managed by Memorandum Macros 

0, [0:?] 

Pi Paragraph indent 

5 (nrof f) 3 (trof f), [0:?] 

Ps Paragraph spacing 

1 (one blank space between paragraphs), [0:?] 

Pt Paragraph type 

(paragraphs always left justified), [0:2] 

Pv "PRIVATE" header 

(not printed), [0:2] 

Rf Reference counter, used by . RS macro 

0, [0:?], incremented by one for each . RS call 

S * t The t r o f f formatter default point size 

10. [6:36] 

S i Standard indent for displays 



* An asterisk attached to a register name indicates this register can be set only from the 
command line or before the macro definitions are read by the formatter. 

t Section 1.3 has notes on setting and referencing registers. Any register having a 
single-character name can be set from the command line. 
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Register Description 



5(nroff)3(troff), [0:?] 

T * t Type of n r o f f output device 

0, [0:2] 

Tb Table counter, used by . tb macro 

0, [0:?], incremented by one for each . TB call 

U * t Underlining style (nrof f ) for . H and . HU 

(continuous underline when possible), [0:1] 

w * t Width of page (line and title length) 

6i, [10:1365] (6i, [2i:7.54i] in the trof f formatter) 



* An asterisk attached to a register name indicates this register can be set only from the 
command line or before the macro definitions are read by the formatter. 

t Section 1.3 has notes on setting and referencing registers. Any register having a 
single-character name can be set from the command line. 
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16.4 Error messages 

Memorandum Macro Error Messages 

An rtim error message has a standard part followed by a variable part. 
The standard part has the form: 

ERROR: (/i/ertaAwe)input line n: 

Variable part n consists of a descriptive message usually beginning 
with a macro name. They are listed below in alphabetical order by 
macro name, each with a more complete explanation. 



Error Message 



Description 



Check TL, AU, AS, 
AE, MT sequence 

Check TL, AU, AS, 
AE, NS, NE, MT 
sequence 

CS: cover sheet too 
long 



DE:no DS or DF 
active 

DF: illegal inside 
TL or AS 

DFrmissing DE 



DF:missing FE 



The correct order of macros at the start of a 
memorandum is shown in section 6.1. 
Something has disturbed this order. 

The correct order of macros at the start of a 
memorandum is shown in section 6.1. 
Something has disturbed this order. Occurs 
if the . AS 2 macro was used. 

Text of the cover sheet is too long to fit on 
one page. The abstract should be reduced or 
the indent of the abstract should be 
decreased. 

A . DE macro has been encountered, but 
there has not been a previous . DS or . DF 
macro to match it. 

Displays are not allowed in the title or 
abstract. 

A . DF macro occurs within a display, that 
is, a . DE macro has been omitted or 
mistyped. 

A display starts inside a footnote. The likely 
cause is the omission (or misspelling) of a 
. FE macro to end a previous footnote. 



4-124 



A/UX Text Processing Tools 



Error Message 



Description 



DF:too many 
displays 

DS: illegal inside 
TL or AS 

DS:missing DE 
DS:missing FE 



FE:no FS active 
FS:missing DE 

FS :missing FE 

H:bad arg -.value 

H: mis sing arg 
Hrmissing DE 

Hrmissing FE 

HUrmissing arg 
LB:missing arg(s) 



More than 26 floating displays are active at 
once, that is, have been accumulated but not 
yet output. 

Displays are not allowed in the title or 
abstract. 

A . DS macro occurs within a display, that 
is, a . DE has been omitted or mistyped. 

A display starts inside a footnote. The likely 
cause is the omission (or misspelling) of a 
. FE to end a previous footnote. 

A . FE macro has been encountered with no 
previous .FS to match it. 

A footnote starts inside a display, that is, a 
. DS or . DF occurs without a matching 

.DE. 

A previous . FS macro was not matched by 
a closing . FE, that is, an attempt is being 
made to begin a footnote inside another one. 

The first argument to the . H macro must be 
a single digit from one to seven, but value 
has been supplied instead. 

The . H macro needs at least one argument. 

A heading macro ( . H or . HU) occurs inside 
a display. 

A heading macro ( . H or , HU) occurs inside 
a footnote. 

The . HU macro needs one argument. 

The . LB macro requires at least four 
arguments. 
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Error Message 



Description 



LB: too many nested 
lists 

LE : mismatched 



LI: no lists active 



LO : LO argument not 
recognized 

LT:LT argument not 
recognized 

ML:missing arg 



ND:missing arg 
RF:no RS active 

RP :missing RF 

RS : mis sing RF 

S:bad arg: value 

SA:bad arg:va/Me 

SG:missing DE 



Another list was started when there were 
already six active lists. 

The . LE macro has occurred without a 
previous . LB or other list-initialization 
macro. This is not a fatal error. The 
message is issued because there exists some 
problem in the preceding text. 

The . LI macro occurred without a 
preceding list-initialization macro. The latter 
probably has been omitted or entered 
incorrectly. 

You have provided an argument to . LO that 
it does not recognize. 

You have provided an argument to . LT that 
it does not recognize. 

The . ML macro requires at least one 
argument. 

The . ND macro requires one argument. 

The . RF macro has been encountered with 
no previous . RS to match it. 

A previous . RS macro was not matched by 
a closing .RF. 

A previous . RS macro was not matched by 
a closing .RF. 

The incorrect argument value has been 
given for the . S macro. 

The argument to the , SA macro (if any) 
must be either or 1. The incorrect 
argument is shown as value. 

The . SG macro occurred inside a display. 
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Error Message 



Description 



SGrmissing FE 
SG:no authors 

Check WA, WE, lA, 
IE, LT sequence 

) W: WA macro 
missing 

)W:WA or WE macro 
missing 

)W:WA, WE, or IE 
macro missing 

VL:missing arg 
WC: unknown option 



The . SG macro occurred inside a footnote. 

The . SG macro occurred without any 
previous . AU macro(s). 

Something has disturbed the correct order of 
these macros. 

If you use . LT, you must specify at least 
one , WA/ . WE pair. 

If you use . WA or .WE, you must specify 
the other member of the macro pair. 

You have omitted either or both of the . lA 
and . IE macros. 

The . VL macro requires at least one 
argument. 

An incorrect argument has been given to the 
. WC macro. 
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Formatter Error Messages 

Most messages issued by the formatter are self-explanatory. Those 
error messages over which the user has some control are listed below. 
Any other error messages should be reported to the local system 
support group. 



Error Message 



Description 



Cannot do ev 



Cannot execute 
filename; 

Cannot o^pen filename'. 



Exception word 
list full; 



Can be caused by: 

• setting a page width that is negative or 
extremely short 

• setting a page length that is negative or 
extremely short 

• reprocessing a macro package (for 
example, performing a , so request on a 
macro package that was already requested 
on the command line) 

• requesting the trof f formatter -si 
option on a document that is longer than 
ten pages. 



Given by the 
not found. 



request if (t\e filename is 



Indicates one of the files in the list of files to 
be processed cannot be opened. 

Indicates too many words have been 
specified in the hyphenation exception list 
(via . hw requests). 



4-128 



A/UX Text Processing Tools 



Error Message 



Description 



Line overflow 



Nonexistent font 
type; 



Indicates output line being generated was 
too long for the formatter line buffer 
capacity. The excess was discarded. Likely 
causes for this message are very long lines 
or words generated through the misuse of 
\c of the . cu request, or very long 
equations produced by eqn/neqn(l). 

Indicates a request has been made to mount 
an unknown font. 



Nonexistent macro 
file; 

Nonexistent 
terminal type; 

Out of temp file 
space; 



Too many page 
numbers; 

Too many number 
registers; 

Too many 
strings/macros; 



Indicates the requested macro package does 
not exist. 

Indicates the terminal options refer to an 
unknown terminal type. 

Indicates additional temporary space for 
macro definitions, diversions, and so on 
cannot be allocated. This message often 
occurs because of unclosed diversions 
(missing . FE or . DE), unclosed macro 
definitions (for example, missing " . . "), or a 
huge table of contents. 

Indicates the list of pages specified to the -o 
formatter option is too long. 

Indicates the pool of number register names 
is full. Unneeded registers can be deleted 
by using the . rr request. 

Indicates the pool of string and macro 
names is full. Unneeded strings and names 
macros can be deleted using the . rm 
request. 
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Error Message Description 



Word overflow Indicates a word being generated exceeded 

the formatter word buffer capacity. Excess 
characters were discarded. Likely causes 
for this message are very long lines, words 
generated through the misuse of \c of the 
. cu request, or very long equations 
produced by eqn/neqn(l). 



4-1 30 A/UX Text Processing Tools 



Chapter 5 
ms and me Reference 



Contents 

1. Introduction 1 

1.1 Definitions 1 

1.1.1 Formatter 1 

1.1.2 Requests 1 

1.1.3 Macros 2 

1.1.4 Strings 2 

1.1.5 Number registers 2 

1.2 How input is read 3 

1.2.1 Arguments and double quotes 3 

1.3 Sequence of beginning macros 3 

2. Changing the overalllook of the document 3 

2.1 Multiple column output 4 

2.2 Setting point size and vertical spacing 5 

2.3 Changing the top and bottom margins 6 

2.4 Changing line length 6 

2.5 Changing page offset 7 

2.6 Changing the tab setting 7 

3. Paragraphs 7 

3.1 Standard paragraph 8 

3.2 Left paragraph 8 

3.3 Indented paragraph 8 

3.4 Exdented paragraph 11 

3.5 Quote paragraph 11 

3.6 Indenting paragraphs 11 

3.7 Changing the spacing between paragraphs .... 12 

4. Headings 12 

4.1 Numbered headings 12 

4.2 Unnumbered headings 14 



I - 



5. Page headers and footers 15 

5.1 Standard headers 16 

5.2 Standard footers 16 

5.3 Custom headers and footers 17 

5.4 Printing a header and/or footer on the first 

page 18 

5.5 Multiline headers and footers 19 

5.6 Set title length 19 

6. Keeps 19 

6.1 Static keeps 20 

6.2 Floating keeps 20 

7. Displays 21 

7.1 ms Displays 21 

7.1.1 ms Standard display format 21 

7.1.2 ms Indented display 22 

7.1.3 ms Left-adjusted display 22 

7.1.4 ms Centered display 22 

7.1.5 ms Block display 23 

7.1.6 ms Display distance 23 

7.2 me Displays 23 

7.2.1 me Major quotes 23 

7.2.2 me Standard lists 24 

7.2.3 me Custom lists 24 

8. Indenting blocks of text 24 

8.1 ms Right shift 24 

8.2 me Centered blocks 25 

9. Tables and equations 25 

9.1 Tables 25 

9.2 Equations 26 

10. Footnotes 27 

10.1 Format of a footnote call 27 

10.2 Changing the footnote style 28 

10.3 Changing footnote indent 28 

10.4 Changing foomote length 29 

11. References 29 



11 - 



12. Creating an index or table of contents 30 

12.1 Index format 31 

12.2 Printing the index in ms 32 

12.3 Printing the table of contents in ms ...... 33 

12.4 Printing the index in xne 33 

13. Basic document formats 33 

13.1 Basic ms formats 33 

13.1.1 ms Cover sheets 33 

13.1.2 ms Titie 34 

13.1.3 ms Authors 34 

13.1.4 ms Abstract 35 

13.1.5 ms Paper styles 35 

13.1.6 ms Chapter title 36 

13.1.7 ms UNIX trademark 36 

13.2 Basic me formats 37 

13.2.1 me Title pages 37 

13.2.2 me Chapter titles 37 

13.2.3 me Thesis format 38 

14. Changing fonts 38 

14.1 Changing the string point size 40 

15. Changing and removing the date in ms 41 

15.1 Changing the date 41 

15.2 Removing the date 41 

16. Drawing boxes 42 

16.1 Boxing a word 42 

16.2 Boxing a block of text 42 

16.2.1 Boxing a block of text in ms 42 

16.2.2 Boxing a block of text in me 42 

17. Checking your work 43 

18. Using nroff/troff commands in ms 43 

19. Creating your own macros 44 

19.1 Conventions used in this reference 44 

19.2 Defining a macro in me 44 

19.3 Format of names used by ms 44 

19.3.1 Names used by eqn/neqn and tbl .... 45 



III - 



20. How ms formats 45 

20.1 FUling 45 

21. Reference tables 46 

21.1 Macro summaries 46 

21.1.1 ms Macro summary 46 

21.1.2 me Macro summary 51 

21.2 Number register summary 53 

21.3 String summary 55 



IV - 



Chapter 5 
ms and me Reference 



1. Introduction 

This is a reference for the ms and me macro packages, ms and me are 
collections of text-formatting macros for the AAJX text formatters 
nrof f and trof f . ms was designed for writing general-purpose 
documents, and me was designed for writing thesis papers at the 
University of California at Berkeley. Some features of me are not 
available in ms, so A/UX Release 2.0 supports both packages. You can 
only use one of these packages at a time, however, so you may wish to 
read this chapter and make a decision about which package to use 
before you actually begin formatting a document. 

It's a good idea to skim this chapter for a general understanding of the 
ms macro package and then read specific sections in detail as needed. 
Unless otherwise indicated, information in this chapter pertains to the 
ms package. In those cases where only me is discussed, or where the 
ms and me packages provide alternate ways of performing similar 
tasks, the macro package to which the information applies is always 
specified. 

For a complete discussion of text-formatting concepts and principles, 
see Chapter 1, "Introduction to AAJX Text Processing." 

1.1 Definitions 

1.1.1 Formatter 

Formatter refers to the nrof f and trof f text formatting programs. 
nrof f and trof f behave similarly, except where noted, 

1.1.2 Requests 

Requests are built-in commands recognized by the formatters. 
Although you seldom need to use these requests directly, this chapter 
refers to some of them. These requests have lowercase names, ms 
macros have uppercase names and me macros have lowercase names 
(for example, . sp is a formatter request, . Ip is an me macro, and 
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. PP is an ms macro). 

1.1.3 Macros 

Macros are named collections of requests. The macro name is used as 
an abbreviation for a collection of commands that you would otherwise 
have to enter explicitly each time they were used, ms and me supply 
many macros, and you can define additional ones. A table at the end of 
this chapter lists the ms and me macros alphabetically. 

1.1.4 Strings 

In ms, strings provide character variables, each of which names a 
string of characters. You can define a string with the . ds (define 
string) command, and call it out in the form \ *x (for one-character 
names), or \ * (xc (for two-character names). For instance, the string 
DY in ms contains the current date. The input line 

Today is \* (DY. 
prints 

Today is October 17, 1989 
You can replace the current date with the command 

.ds DY 02/21/90 

A table at the end of this chapter lists the ms string names 
alphabetically. 

1.1.5 Number registers 

Number registers are integer variables, ms uses them to set default 
measurements such as line length, header and footer margins, and page 
offset. You can give a register a value with the . nr command. For 
example, the following sets the value of the line length register, LL: 

.nr LL 4i 

This instructs the formatter to generate all text lines at 4 inches. To 
reset this value to the default, enter the following: 

.nr LL 

A table at the end of this chapter lists the ms number registers 
alphabetically. 
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1 .2 How Input is read 

Formatters fill output lines from one or more input lines. You can 
justify output lines so that both the left and right margins are aligned. 
As lines are being filled, words may also be hyphenated as necessary. 
You can turn any of these modes on and off (with the . na, . ad, . hy, 
. nf , and . f i formatter requests). Turning off fill mode also turns off 
justification and hyphenation. Certain formatting commands (requests 
and macros) stop filling the current output line, print the line (of 
whatever length), and begin subsequent text on a new output line. This 
printing of a partially filled output fine is called a break. A few 
formatter requests and most of the ms macros cause a break. See 
"How ms Formats" for more information. 

1 .2.1 Arguments and double quotes 

In ms and me, you can use an argument to modify a macro. For 
example, the ms macro . DS begins a standard display. When you add 
a C to the macro 

.DS C 

the material in the display is centered. 

Any macro argument containing ordinary (paddable) spaces must be 
enclosed in double quotes. A double quote (") is a single character that 
must not be confused with two apostrophes (' ' ). acute accents ( ' '). or 
grave accents C"). If an argument containing such spaces is not 
enclosed in double quotes, it will be treated as several separate 
arguments. 

1.3 Sequence of beginning macros 

Text files processed by the ms macros must begin with one of the 
following macros: . TL, . SH, . nh, . pp, or . LP. 

Text files processed by the me macros must begin with one of the 
following macros: . pp, . Ip, . ip, . np, . sh, or . uh. 

These macros initialize the file and must precede a break caused by 
blank lines, leading spaces, or . sp, . br, and . ce trof f requests. 

2. Changing the overall look of the document 

A document formatted with the ms or me macros is produced in a 
standard page layout. By default, text is generated in a single column 
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and a line of text is 6 inches from margin to margin. The left margin is 
1 inch (in t rof f ) from the edge of the paper, point size is set to 10 
points, vertical space is set to 12 points, and tab stops are set every 5 
spaces. 

The following macros and number registers permit you to change these 
default features and customize your page layout. 

2.1 Multiple column output 

Output from t rof f is normally a single column of text By placing 
the ms command . 2C or the me command . 2c in your file, the output 
is printed in two-column format. Each column is printed with a width 
of 7/15 of the current line length and the gap between the two columns 
is 1/15 of the full line length. 

To print text in more than two columns, use the ms . MC macro: 

. MC column-width gutter-width 

The number of columns is computed automatically, based on the 
maximum number of columns of the specified width that can fit within 
the current line length. The column width argument must be numeric, 
and unless indicated otherwise, the unit of measurement is assumed to 
be in ens. 

The gutter-width argument permits you to control the distance between 
columns. 

To return to single-column output, use the . IC command. 

Any change in the number of columns specified (except from one to 
two or greater) causes a page break. 

In me, you can request a new column with . be. To revert back to 
single column output, use . Ic. 
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Type 


Form 


Explanation 


inms: 






macro 


.2C 


Print text in two equal columns. 


inxne: 






macro 


.2c 


Print text in two equal columns. 


in ins: 






macro 


.MCxy 


Print text in multiple columns, x is the 
column width, and y is the gutter width. 


in me: 






macro 


.be 


Begin new column. 


inms: 






macro 


.IC 


Restore one-column printing. 


in me: 






macro 


.Ic 


Restore single-column output. 



2.2 Setting point size and verticai spacing 

Number registers are used to set default point size and vertical spacing. 
In ms the registers are called PS and VS. In me, there is a register for 
paragraph point size, . nr pp; a register for section header point size, 
. nr sp; and a register for title point size, . nr tp. (To change 
relative point size using macros, see "Changing the String Point 
Size.") The defaults for point size and vertical spacing in the ms 
macro package are 10 and 12 points, respectively. In me, the default 
point size for regular text is 10 points, and the default point size for 
footnotes is 8 points. The 2-point difference allows for adequate 
spacing between lines. 

When using ms, remember to change the vertical spacing register when 
changing the point size. Otherwise, the output will be either too widely 
or too closely spaced. In me, the vertical spacing is set to be 
proportional to the type size. 
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Type 


Form 


Explanation 


inms: 

register 


PS 


Point size. 
Initial value: 10 


inxne: 
register 


.nr pp 


Paragraph point size. 
Initial value: 10 


register 


.nr sp 


Section heading point size. 
Initial value: 10 


register 


.nr tp 


Title point size. 
Initial value: 10 


register 


VS 


Vertical spacing. 
Initial value: 12v 



2.3 Changing the top and bottom margins 

By default, the distance between the header and footer text and the top 
and bottom edges of the paper is 1 inch. In ms, you can change these 
values by resetting registers hm and FM. 



Type 



Form 



Explanation 



register hm 



register FM 



Vertical distance of the header margin. 
Initial value: li 

Vertical distance of the footer margin. 
Initial value: li 



2.4 Changing line length 

The default length of a line of text is 6 inches from left to right margin. 
In ms, you can change this by resetting the number register LL. 



Type 



Form 



Explanation 



register ll 



Line length. 
Initial value: 6i 
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2.5 Changing page offset 

The position of the left margin is determined by two dimensions: page 
offset and indentation. Indentation controls the current left margin, 
whereas page offset controls the absolute left margin. 

Page ofTset is the distance betweeen the left margin and the left edge of 
the paper. Indentation is expressed as a distance to the right of page 
offset. You can change indentation within your document (see 
"Indenting Paragraphs"), but page offset is defined at the beginning of 
your document and usually remains constant throughout. 

The default page offset is 1 in t rof f and in nrof f . In ms, you can 
change this by resetting number register PO. The value of number 
register PO multiplied by 2 plus the line length (register LL) must 
always equal 8. For example, 

1x2+6=8 

where 1 is the default page offset and 6 is the default line length in 

troff. 



Type Form Explanation 



register p o Absolute limit of the left margin. 

Initial value: li in troff, in nrof f 



2.6 Clianglng the tab setting 

In ms, you can set tabs with the . TA command. The default settings 
are in increments of 5 ens, but you may substitute any value needed. 



Type Form Explanation 



macro . TA x Set tabs to x, where x is the number of 

ens. 
Initial settings: increments of 5 ens 



3. Paragraphs 

The ms and me macro packages provide several commands that 
determine the style of your paragraph. In all cases, the formatter skips 
one vertical space before generating the text of the paragraph. 
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3.1 Standard paragraph 

The first line of a standard paragraph is indented. All other lines are 
generated at the left margin. The default indentation is 5 ens, but can 
be changed by setting the number register Pi (see "Indenting 
Paragraphs," later in this chapter.) 



Type 


Form 


Explanation 


inms: 






macro 


• pp 


Standard paragraph. The first line is 
indented the value of register pi (5 
ens). The paragraph is preceded and 
followed by a vertical space equal to the 
value set in register pd (Iv). 


in me: 






macro 


• pp 


Standard paragraph. 



3.2 Left paragraph 

The text of a left-block paragraph is generated as a left-adjusted block. 



Type 



Form 



Explanation 



inms: 

macro 



mme: 
macro 



LP 



IP 



Left-block paragraph. The paragraph is 
offset vertically by the value of register 
PD (Iv). 

Left-block paragraph. 



3.3 Indented paragraph 

All lines of an indented paragraph are indented a certain value. In ms, 
the . IP command can'be used in three ways: 

.IP 

.IP label 

.IP label value 
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The first example produces a basic indented paragraph. Text is 
generated as a block five spaces from the left margin. 

The other two forms of the indented paragraph command permit you to 
label your paragraph with some alphanumeric character. These can be 
used to produce numbered or bulleted lists. For example, 

.IP (1) 

This is a labeled indented paragraph. 

produces 

(1) This is a labeled indented paragraph. 

You can substitute any character for the number. For example, 

.IP * 

This is a labeled indented paragraph. 

produces 

* This is a labeled indented paragraph. 
You can also assign a value for the indentation level: 

.IP (1) 10 

Instead of the default indentation (5 ens), the formatter now indents the 
text 10 ens. 

In me, the similar command . ip can also be used in three ways: 

.ip 

.ip label 

.ip label value 

The first example produces a basic indented paragraph. Text is 
generated as a block five spaces from the left margin. 

The other two forms of the indented paragraph command permit you to 
label your paragraph with some alphanumeric character. These can be 
used to produce numbered or bulleted lists. For example, 

.ip (1) 

This is a labeled indented paragraph. 
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produces 

(1) This is a labeled indented paragraph. 

You can substitute any character for the number. For example, 

.ip * 

This is a labeled indented paragraph. 

produces 

* This is a labeled indented paragraph. 
You can also assign a value for the indentation level: 

.ip (1) 10 

Instead of the default indentation (5 ens), the formatter now indents the 
text 10 ens. 



Type 


Form 


Explanation 


inms: 






macro 


.IP [xy] 


Indented paragraph, where x is the label 
and y is the indentation. Default 
indentation is 5 ens, as set in the 
register p I . The paragraph is offset 
vertically by the value of register pd 
(Iv). 


in me: 






macro 


.ip[xy] 


Indented paragraph, where x is the label 
and y is the indentation. Default 
indentation is 5 ens. The number 
register for setting paragraph 
indentation is ii. 


macro 


.np 


Numbered indented paragraph. The 
numbering is reset at the next . pp, 
.lp,or .sh. 
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3.4 Exdented paragraph 

The first line of text in an exdented paragraph (hanging indent) is flush 
with the left margin; all subsequent lines are indented the default 5 ens. 
This ms macro is often used to format bibliographic references. 



Type Form Explanation 



macro . XP Paragraph with the first line exdented 

by the value of register P I (5 ens). The 
paragraph is offset vertically by value 
of register PD (Iv). 



3.5 Quote paragraph 

In ms, a quote paragraph is indented 5 ens from both the left and right 
margins. Subsequent text is centered and generated as an offset block. 



Type 


Form 


Explanation 


macro 


• QP 


Quote paragraph. The paragraph is 
centered and indented left and right by 
the value of register Qi (5 ens), and 
offset vertically by the value of register 
PD (Iv). 



3.6 Indenting paragraphs 

In ms, the registers PI and Qi determine the amount of indentation for 
paragraphs. Values for each must be unsealed and are always read as 
ens. For example, 

.nr PI li 

will not work. The value 1 i (1 inch) will not be understood by 
t rof f ; it must be given in ens. 

PI sets the indentation level for all paragraphs except quote 
paragraphs. For quote paragraphs, use the QI form. 
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Type 


Form 


Explanation 


inms: 






register 


PI 


Paragraph indentation. The values must 
be unsealed and are read as ens. 
Initial value: 5 ens 


inxne: 






register 


i 


Paragraph indentation. The values are 
unsealed and are read as ens. 


inms: 






register 


QI 


Quoted paragraph indent. The values 
must be unsealed and are read as ens. 
Initial value: 5 ens 



3.7 Changing the spacing between paragraphs 

The default distance between paragraphs is one vertical space. To 
change this value in ms, reset register pd. 



Type 



Form 



Explanation 



register pd 



Paragraph distance. 

Initial value: Iv in nrof f , 0.3 v in 

troff 



4. Headings 

Two types of section headings are available with these macro 
packages: unnumbered and numbered. In both cases, the heading is on 
the left margin and is preceded by one blank line, and the text of the 
section is immediately following the heading (without a blank line). In 
troff the heading is printed in boldface; in nrof f it is underlined. 
A paragraph macro must follow the heading macro if a vertical space 
or indentation is desired. 

4.1 Numbered headings 

In ms, the . NH macro produces automatically numbered section 
headings. An optional level number indicates a subsection from 1 to 5. 
For example. 
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.NH 1 

First-level heading 

• LP 
text 

.NH 2 

Second-level heading 

• LP 
text 

produces 

1. First-level heading 

text 

1.1 Second-level heading 

text 

In me, the same thing can be accomplished with the . sh macro. For 
example, 

. sh 1 First-level heading 

.Ip 

text 

.sh 2 

Second-level heading 

.Ip 

text 

produces the output: 

1. First-level heading 

text 

1.1 Second-level heading 

text 
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Type 



Form 



Explanation 



inxas: 

macro 



inzoe: 
macro 



, NH [x] Begin automatically numbered heading, 

where x is the heading level number (1 
through 5). If ;c=0, numbering is reset 
too. 

, sh U] Begin automatically numbered heading, 

where x is the heading level. 
Numbering is reset at new paragraph 
request. (The argument number can 
also be placed after the title of the 
section, as in . sh "title" 1). 



me also has the ability to indent sections proportionally to the depth of 
the section. The command 

.nr sxNx 

will cause each section to be indented by N. N must have a scaling 
factor of the form x, where x is the unit N is measured in. The most 
common units are i for inches, c for centimeters, and n for ens (the 
width of a single character). 



Type 



Form 



Explanation 



in me: 

macro 



si [Nx] Indented section heading. Indents each 
section by N in ;c units in the section 
number. 



4.2 Unnumbered headings 

The ms macro . SH produces section headings that are not numbered. 
In me, you can accomplish the same thing with the macro . uh. 
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Type 


Form 


Explanation 


in ins: 






macro 


.SH 


Begin left-adjusted section heading, 
separated from the preceding text by 
one vertical space. 


in me: 






macro 


.uh 


Begin left-adjusted section heading, 
separate from the proceeding text by 
one vertical space. 



5. Page headers and footers 

Text printed at the top of each page is called a page header. Text 
printed at the bottom of each page is called a page footer. You can 
specify three separate headers and footers (left, center, and right) using 
either string registers or macros. 

In ms, six string registers set up the standard layout of headers and 
footers. Those registers that do not have predetermined default values 
are set with the following command: 

. ds register-name text 

For example, to print the word "DRAFT" in the lower-right comer of 
every page of a document, define register rf (right footer) as follows: 

.ds RF DRAFT 

To clear the register, use this command: 

. rm RF 

You can use these macros to create custom headers and footers that 
appear on even or odd pages. Arguments to these macros must be 
enclosed within a set of four apostrophes indicating placement on the 
line within three fields (left, center, and right). For example, 

. OH ' left ' center ' right' 

In me, simple requests handle headers and footers. They are three-part 
titles, as in ms, and a percent sign is used for the current page number: 
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.he '%' 

.fo 'Successful Author' 'My Story' 

This will produce output with the current page number centered at the 
top of each page, "Successful Author" in the lower left comer, and 
"My Story" right-adjusted in the lower right comer. 

The ms macro package has many other ways of dealing with headers 
and footers. The next sections explain these ms macros. 

5.1 Standard headers 

In ms, use the following string registers to store text put in the left, 
center, and right headers. Only the center header (register CH) contains 
a default string. In both nrof f and trof f , unless specified 
otherwise, register CH contains the current page number surrounded by 
hyphens. If you don't want a centered page number, you can easily 
remove it or move it to another position. The remaining fields must be 
set manually. 



Type 


Form 


Explanation 


register 


LH 


Left header 


register 


CH 


Center header 

Initial value: current page number 

surrounded by hyphens 


register 


RH 


Right header 



5.2 Standard footers 

In ms, use the following string registers to store text put in the left, 
center, and right footers. In nrof f the center footer (CF) contains the 
current date as the default string. In trof f this field is empty. 
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Type 


Form 


Explanation 


register 


LF 


Left footer 


register 


CF 


Center footer 

Initial value: current date (nrof f 

only) 


register 


RF 


Right footer 



5.3 Custom headers and footers 

You can specify lieaders and footers on even- and odd-numbered pages 
by defining macros .EH, .OH, .EF, and .OF. 

For example, if you want the title of your document to be in the left 
footer on even-numbered pages and in the right footer on odd- 
numbered pages, use the following commands: 



EF 
OF 



'title'" 
' ' ' title' 
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Type 



macro 



Form 



Explanation 



macro 



macro 



macro 



.EH['/'c'r'] Print page header only on even pages . 
The three strings specified between the 
four apostrophes indicate left, center, 
and right When used without 
arguments, cancel previously specified 
even header. 

.0H[' I' c'r'] Print page header only on odd pages. 
The three strings specified between the 
four apostrophes indicate left, center, 
and right. When used without 
arguments, cancel previously specified 
odd header. 

. EF['^ I' c' r'] Print page footer only on even pages. 
The three strings specified between the 
four apostrophes indicate left, center, 
and right. When used without 
arguments, cancel previously specified 
even footer. 

.0F[' I' c'r'] Print page footer only on odd pages. 

The three strings specified between the 
four apostrophes indicate left, center, 
and right. When used without 
arguments, cancel previously specified 
odd footer. 



5.4 Printing a header and/or footer on the first page 

By default, the printing of headers and footers begins on page two of 
your document. To print a header, a footer, or both on page one of your 
document, use the ms macro .PI; this will print whatever is defined as 
your header or footer in the registers or in the macros. It must be used 
before the beginning of the text. 
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Type Form Explanation 

macro . P 1 Print header and/or footer on the first 

page of the document. Must be placed 
at the beginning of the text. 



5.5 Multiline iieaders and footers 

In ms, the . PT (page title) and . BT (bottom title) commands are used 
to define macros for multiline page headers and footers. Define this 
macro at the beginning of your file. For example, 

.de PT (or .BT) 

. 1 1 ' left ' center ' right ' 

. 1 1 'left' center ' right ' 

If you need a three-line header or footer, add the formatting instruction 

'sp-1 

before the first . tl instruction so the header lines will begin one line 
higher on the page. Make sure you use an apostrophe (' ) and not a 
period (.) with the ' sp-1 instruction. (See Chapter 3, 
"nrof f /t rof f Reference," for a full explanation of the difference 
between the apostrophe and the period in trof f requests.) 

After you have defined these macros, the system automatically uses the 
new definition when a page is begun. 

5.6 Set title length 

In ms, register LT determines horizontal distance available for headers 
and footers. By default, it is equal to the line length (LL). 



Type Form Explanation 



register lt Total length of headers and footers. 

Initial value: 6i (or the same as register 

LL) 



6. Keeps 

The ms and me macro packages provide commands to keep a block of 
text together on one page. There are two ways to do this: the standard 
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(or static) keep and the floating keep. 
6.1 Static keeps 

In ms, the static keep begins with . KS and ends with . KE. In me this 
is accomplished with the block macros . (b and . ) b. If the number of 
lines within these two macros exceeds the remaining lines on the page, 
a page break is forced and the material in the block is printed on the 
next page. 



Type 


Form 


Explanation 


inms: 






macro 


.KS 


Begin static keep. 


in me: 






macro 


. (b 


Begin static keep. 


inms: 






macro 


.KE 


End static or floating keep. 


in me: 






macro 


.)b 


End static keep. 



6.2 Floating l<eeps 

In ms, the floating keep begins with . kf and ends with . KE. In me 
this is accomplished with the . ( z and . ) z macros. If the number of 
lines in a block of text exceeds the remaining lines on the page and it is 
necessary to force a page break, the regular text material continues to 
print until it reaches the end of the page, and the block of text is 
printed. It differs from a static keep in that it waits for a natural page 
break rather than forcing one. 



5-20 



A/UX Text Processing Tools 



Type 


Form 


Explanation 


inms: 






macro 


.KF 


Begin floating keep. 


inms: 






macro 


. (z 


Begin floating keep. 


in ins: 






macro 


.KE 


End static or floating keep. 


in me: 






macro 


.)z 


End floating keep. 



7. Displays 

Displays format text without filling or adjusting. Several types of 
displays are available with ms and me, both those with keep and those 
without. However, the philosophy of displays is slightly different in 
each macro package, so the ms and me display macros are discussed 
separately in the sections that follow. 

If you want text to be kept on a single page, use the standard ms 
display ( . DS [x]), where x can designate left, right, centered, or block. 

If you don't want the text to be kept on a single page, use the ms 
displays without keep ( . ID, . LD, . CD, . BD). 

7.1 ms Displays 

7.1.1 ms standard display format 

A standard display is automatically put into a keep (see "Keeps"). A 
standard display can be indented, left adjusted, centered, or in block 
format depending on the argument you use. 
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Type 



macro 



Form 

.DS [xy] 



macro 



,DE 



Explanation 

Start displayed text. The text is 

formatted without filling or adjusting, x 

determines the format of the display: 

x=l indented 

x=L left adjusted 

x=C each line centered 

x=B lines centered as a group 

y sets the amount (in ens) of indentation 

(the default is the value of register P i , 

or 5 ens). 

End display. 



7.1.2 ms indented display 

The indented display is the same as . DS I except that it does not 
invoke a keep. Displayed material is formatted 5 ens to the right of the 
left margin (or the value of register pi). 



Type 



Form 



Explanation 



macro 



• ID 



Indented display (no keep). 

Initial value: amount of register p I (5 

ens) 



7.1.3 ms Left-adjusted display 

The left-adjusted display is the same as . DS L except that it does not 
invoke a keep. Displayed text is formatted in a block at the left margin. 



Type 



Form 



Explanation 



macro 



LD 



Left-adjusted display (no keep). 



7.1.4 ms Centered display 

The centered display is the same as . DS C except that it does not 
invoke a keep. Each line of text is centered individually. 
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Type 



macro 



Form 



CD 



Explanation 

Centered display (no keep). Lines are 
centered individually. 



7.1.5 ms Block display 

The block display is the same as . DS B except that it does not invoke 
a keep. Displayed text is centered and left adjusted as a group. 



Type 



Form 



Explanation 



macro 



BD 



Left adjusted then centered display (no 
keep). 



7.1.6 ms Display distance 

Display distance is the amount of vertical space surrounding a display. 
The default settings are one vertical space (nrof f ) or one-half vertical 
space (trof f ). It is set with register dd. 



Type 



Form 



Explanation 



register DD 



Vertical distance surrounding displays. 
Initial value: one vertical space in 
nrof f ; one-half vertical space in 
troff 



7.2 me Displays 

7.2.1 me Major quotes 

Major quotes are more than one line long and need to be set apart from 
the rest of the text without quote marks around them. This can be 
accomplished with the . (q and . ) q macros. 



Type 



Form 



Explanation 



macro . (q 

macro . ) q 



Begin major quote display. 
End major quote display. 
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7.2.2 me Standard lists 

Lists are indented, single spaced, unfilled displays. They're used when 
the text should stand out from the normal text, as with columns of 
figures or examples. The macros . (1 and . ) 1 are used to display 
lists. 



Type 



Form 



Explanation 



macro . (1 

macro . ) 1 



Begin list display. 
End list display. 



7.2.3 me Custom lists 

You can build fancier lists in me by utilizing the fill mode. By default 
lists are normally collected in nofill mode, but the addition of a capital 
F as an argument to the list macro will cause the list to be indented 
from both margins. 

If you wish to center a list, use the C argument, and use the L argument 
to left justify your list. 



Type 


Form 


Explanation 


macro 


. (1 F 


Begin list in fill mode. 


macro 


.)1 


End list in fill mode. 


macro 


. (1 C 


Begin centered list display. 


macro 


.)1 


End list display. 


macro 


.)1 L 


Begin left-adjusted list display. 


macro 


. (1 


End list display. 



8. Indenting blocks of text 

Both ms and me have facilities for indenting blocks of text, ms can 
shift text to the right, and me can center text blocks. 

8.1 ms Right shift 

The . RS macro shifts the text to the right. The default value for the 
shift is 5 ens, but this can be changed by resetting number register P i . 

You can use more than one . RS to increase the amount of indentation. 
The only Umit is the right margin. For each . RS entered, you must 
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enter an . re to cancel it. For example, if you enter five . RS macros, 
you must enter five . RE macros. 



Type 


Form 


Explanation 


macro 
macro 


.RS 
• RE 


Right shift. Move indentation to the 
right by the value of register Pi (5 ens). 
. RS macros can be nested. 

End right shift. Move indentation to the 
left by the amount that the 
corresponding . RS is moved to the 
right. 



8.2 me Centered blocks 

Sometimes you may want to center several lines of text as a group, 
rather than centering each line separately. This can be accomplished 
with the . (c and . ) c macros. All the lines between these macros will 
be centered as a unit, with the longest line centered on the page and the 
rest of the Unes centered around it. Centered blocks are not keeps, but 
you may use them inside keeps. 



Type Form Explanation 



macro . (c Begin centered block, 

macro . ) c End centered block. 



9. Tables and equations 

The following ms macros are used with the AAJX system 
preprocessors tbl and eqn to produce tables and equations. For 
complete instructions on using these programs, see Chapter 6, "tbl 
Reference," and Chapter 7, "eqn Reference.'* 

9.1 Tables 

Text placed between the delimiters . TS and . te (table start and table 
end) are processed by the table formatting program tbl. If you are 
producing a multipage table and you want a standard heading to be 
printed on each page of the table, you should use the . TS H form of 
the command. Type . TH at the end of the heading material. For 
example. 
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.TS H 

center tab ( : ) ; 

c c . 

.TH 

keading'.data 

table'.data 

table'.data 

.TE 

repeats the heading 

heading data 

on every page. (This is not a feature of tbl but of ms.) 



Type 


Form 


Explanation 


macro 


.TS [H] 


Table start. Supplies one-half vertical 
space between preceding text and table. 
Argument H indicates that the material 
that follows (until a . TH) is heading 
text to be repeated for multipage tables. 


macro 


.TE 


Table end. 


macro 


.TH 


End table heading. Used only with the 
.TS H macro. 



9.2 Equations 

Text placed between the delimiters . EQ and . EN (equation start and 
equation end) are processed by the equation formatting program eqn. 

You must use displays with keep ( . DS / . DE) around displayed 
equation specifications. (See Chapter 7, "eqn Reference," for a 
discussion of the difference between displayed and in-line equations.) 

By default, displayed equations are centered. You can specify the 
placement (centered, left adjusted, or indented) by supplying the 
appropriate argument to the . EQ command. Following this argument, 
you can also specify an equation number to label the equation. The 
label is generated at the right margin. For example. 
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.DS 




•EQ (1) 




sum from i=0 to 


{i = inf} X sup i 4 over pi 


.EN 




.DE 




produces 




z^ - 


(1) 


Type Form 


Explanation 


macro .EQ [xy] 


Begin equation. Output preceded by 




one vertical space and automatically 




centered, x controls the placement of 




the equation: 




x=L left adjusted 




x=l indented 




x=C centered 




Argument y supplies an equation 




number and prints it at the right margin. 


macro . EN 


End equation. 



10. Footnotes 

1 0.1 Format of a footnote call 

You can produce footnotes with ms by placing text between footnote 
start and end macros, . FS and . FE. In me this is accomplished with 
. ( f and . ) f . The material is collected, saved, and printed at the 
bottom of the current page. The footnote is printed 2 points smaller 
than the text, and is separated from the main body of text by a 
horizontal line. 

You can produce footnotes that are numbered automatically by placing 
the string \** immediately following the text to be footnoted, ms also 
permits you to define your own footnote label. For example, if you 
want your footnotes to be labeled alphabetically, you can enter the 
following: 
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.LP 

This is the sentence I am referencing [A] 

• FS 

[A] This is the text of the footnote. 

.FE 



Type 


Form 


Explanation 


inms: 






macro 


.FS 


Begin footnote. 


inxne: 






macro 


. (f 


Begin footnote. 


inms: 






macro 


.FE 


End footnote. 


in me: 






macro 


.)f 


End footnote. 



10.2 Changing tine footnote style 

In a standard footnote, a label is printed as a superscript and the first 
line is indented. You can suppress both these features with ms, as well 
as produce the footnote text as an indented paragraph. Use the number 
register ff to modify the default format of a footnote. 



Type 


Form 


Explanation 


register 


FF X 


Footnote format. 

x=l Suppress superscripting of 

footnote label. 
x=2 Suppress indentation of first line 

of footnote text. 
jc=3 Footnote as indented paragraph. 



10.3 Clianging footnote indent 

In ms, the footnote indent register is used to change a footnote's 
distance from die left margin. The default is 2 ens. 
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Type Form Explanation 

register Fl Footnote indent Controls the amount 

of indentation from the left margin. 
Initial value: 2 ens 



10.4 Changing footnote length 

By default, the length of a footnote is 5.5 inches, just slightly shorter 
than the default line length. You can change this value with ms by 
resetting register FL. 



Type Form Explanation 



register FL Footnote line length. 

Initial value: 5.5i 



In addition to standard footnotes, me has a delayed text facility. This is 
similar to a footnote except that it is printed only when explicitly called 
for (usually at the end of a chapter). The macro to identify delayed text 
in me is * #. Even if you are using the delayed text as your standard 
reference mechanism, you may still use the footnote facility, but in this 
case you may wish to reference the footnotes with special characters 
rather than numbers. 

11. References 

You can classify books, journal articles, book chapters, and reports 
with the ms macros . ] -, . [0, and . [n. They must be used in 
conjunction with the trof f preprocessor refer. See ref er(l) in 
A/UX Command Reference. 
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Type 


Form 


Explanation 


macro 


.]- 


Begin refer reference. 


macro 


.[0 


End of unclassifiable reference. 


macro 


. [n 


Classifiable reference. 
n=l journal article 
n=2 book 
n=3 book article 
n=4 report 



12. Creating an index or table of contents 

You should enclose all entries you want placed in an index in the ms 
begin and end delimiters . XA and . XE. Additional entries are 
preceded by the macro . XA. 

In ms, these macros can be used throughout the body of text in 
combination with section heading macros to automatically generate a 
table of contents with page numbers. For example, 

.SH 

heading-text 
.XS 1 
heading-text 
.XE 

If you are using numbered headings in ms and you want these numbers 
included in the table of contents, use this format: 

.NH 

heading-text 

.XS 1 

\ * ( SN heading-text 

.XE 

The \ * ( SN string will be replaced with the number of the heading 
when the table of contents or index is printed. 

The final output of the index or table of contents is produced with 
either the . PX or the . TC macro. The difference between these 
macros is that . TC prints a centered "CONTENTS" heading at the top 



5-30 A/UX Text Processing Tools 



of the page and page numbering is reset to roman numerals (as in this 
document). 

12.1 Index format 

Material to be printed in an index or table of contents should be placed 
between the . XS and . XE macros, if you're using ms, or between . (x 
and . ) f , if you're using me. In ms, use the . XA macro for additional 
ms entries: 

.XS 
index-entry 

.XA 

additional-index-entry 
.XA 

additional-index-entry 
.XE 

You can designate the page number of the indexed material as an 
argument to .XS or . (x: 

.XS page-number 
. (x page-number 

In ms, you can change the indentation level by assigning a value to the 
argument following the page number: 

.XS 1 5 
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Type 


Form 


Explanation 


inms: 






macro 


• xs [xy] 


Begin index entry, where x is the page 
number of the entry and y is the amount 
of indentation (in ens). 


in me: 






macro 


. (X [n] 


Begin index entry, where n is the page 
number of the entry. If «=_, no page 
number or line of dots will be printed. 
If «=" ", a line of dots will appear with 
no page number. If n is any other 
character, it will be understood as the 
name of the index, thus allowing 
several indices to be run 
simultaneously. 


inms: 






macro 


.XA[xy] 


Additional index entry, where x is the 
page number of the entry and y is the 
amount of indentation (in ens). 


macro 


.XE 


End index entry. 


in me: 






macro 


.)x 


End index entry. 



12.2 Printing the index in ins 

The . PX macro is used in ms to print a formatted list of the text items 
designated by the index macros. This is accomplished in me by . xp. 



Type 


Form 


Explanation 


inms: 






macro 


.PX 


Print index. 


in me: 






macro 


.xp 


Print index. 
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12.3 Printing tiie tabie of contents in ms 

The . TC macro prints a list of the text items designated by the index 
macros. It differs from the . PX macro described above in two ways: 

• It provides a centered heading ("CONTENTS") at the top of the 
page. 

• It resets page numbering to lowercase roman numerals. 



Type Form Explanation 



macro .TC Print table of contents. Preceded by 

page break, and the page numbering is 
reset to lowercase roman numerals. 



12.4 Printing tlie index in me 

In me, the index must be printed at the end of the paper, rather than at 
the beginning. You will have to rearrange the paper physically after 
printing if you wish to use the me index as a table of contents. 

13. Basic document formats 

Both the ms and the me macro packages have facilities for formatting 
the basic elements of a document, such as the cover page, margins, and 
spacing. The philosophy is slightly different for each (rae was 
developed to follow the specifications for doctoral dissertations at the 
University of California at Berkeley), so the basic formatting facilities 
of each macro package are described separately in the sections that 
follow. 

13.1 Basic ms formats 

13.1.1 ms Cover sheets 

You can generate a separate cover sheet containing any of the 
following: title ( . TL), author ( . AU) , author's institution ( . Al), and 
abstract ( . ab) . Precede these macros with . rp and enter them in the 
order indicated. The current date is printed on the cover sheet (unless 
you suppress this feature with the . ND macro; see "Removing the 
Date"). 

You can also include this information without producing a cover sheet. 
Title, author, abstract, and so on are then printed on the first page of the 
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document. 

13.1.2 ms Title 

The title macro ( . TL) creates a centered title (as opposed to the three- 
part title format of the t rof f request . tl). In t rof f the title is 
printed 2 points larger than the remaining text and is in boldface. In 
nrof f the title is underlined. When used with the . rp macro, the title 
is centered on the cover sheet. 



Type Form Explanation 



macro . TL Print centered title in boldface, 2 points 

larger than current font. 



13.1.3 ms Authors 

The macros . AU and . A I print the author's name and institution 
centered and in italics. For example, 

.AU 

author' s-name 

.AI 

author' s-institution 

produces 

author' s-name 

author' s-institution 

Multiple authors (and institutions) can also be used. Precede each 
additional entry with . AU or . Al, as appropriate. For example, 

.AU 

author! 

.AU 
author2 
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Type 


Form 


Explanation 


macro 
macro 


.AU 
.AI 


Print centered author's name, in current 
point size and in italics. Multiple 
names are printed on separate lines if 
entered on separate input lines. 

Print centered information about the 
author's institution. 



13.1.4 ms Abstract 

An abstract is a brief summary of the text it precedes. The . ab macro 
prints this summary after the author's institution, if used, with an 
optional centered heading. 



Type 


Form 


Explanation 


macro 


.AB [no] 


Begin abstract. The abstract text is 
preceded by a centered heading titled 
"ABSTRACT." Argument no 
suppresses the heading. The abstract 
text is filled and adjusted on a line 5/6 
the normal text line length. 


macro 


.AE 


End abstract. 



13.1.5 ms Paper styles 

You can produce cover sheets in two basic formats: standard released 
paper or thesis mode. 

Released paper format ( . RP) provides a separate cover sheet 
containing title, author, institution, and abstract. (See "ms Cover 
Sheets.") 

Thesis mode ( . tm) formats your document according to university 
specifications for doctoral dissertations. The page number is printed on 
each page, text is double-spaced, the current date is removed from the 
center footer, and the chapter title macro ( . CT) is defined and 
activated. 
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Type 



macro 



Form 

.RP [no] 



macro 



.TM 



Explanation 

Released paper format. Provides a 
separate cover sheet for title, author, 
author's institution, and abstract. This 
information is repeated on the first page 
of the document unless the argument 
no is specified. 

Thesis mode. Automatically numbers 
each page; double-spaces all text except 
displays, quotes, and keeps; suppresses 
the printing of the date in the center 
footer; and defines the chapter title 
macro ( . CT). 



13.1.6 ms Chapter title 

The chapter title macro is defined only when you have invoked thesis 
mode. It begins a new page, moves the page number from the right 
header to the center footer, centers the lines that follow until a 
paragraph macro is reached, and, in the case of t rof f , prints these 
lines in boldface. 



Type 


Form 


Explanation 


macro 


.CT 


Move the page number from right 
header to the center footer, generate a 
page break, and center and boldface the 
lines following the request (thesis mode 
only). 



13.1.7 ms UNIX trademarlc 



Type 



Form 



Explanation 



macro 



,ux 



Prints "UNIXt" in the text plus a 
footnote that reads "UNIX is a 
Trademark of Bell Laboratories." 
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13.2 Basic me formats 

13.2.1 zne Title pages 

There are no headers or footers on a title page, and unlike other pages, 
you are allowed to leave blank space by spacing down from the top. 
The . tp macro produces a title page. 



Type Form Explanation 



macro .tp Print title page. 



13.2.2 me Chapter titles 

The . +c r macro can be used to start chapters in me. Each chapter is 
automatically numbered from one, and a heading is printed at the top of 
each chapter with the chapter number and the name T. This 
information is moved to the footer of the first page of the chapter. If 
the name T is not specified, the output is a chapter with no heading. 

Although a document's preliminary sections — ^the abstract, table of 
contents, and so on — are normally placed at the beginning, you should 
format and print them last when using me. This is so that index entries 
can be collected and then printed for the table of contents. At the end 
of the document's main text, you can use the . ++P macro, which 
begins the preliminary sections. After issuing this request, you can use 
the . +c macro to begin one preliminary section of the document and 
print the page numbers in lowercase roman numerals. 

You can use the . +c macro repeatedly to begin different preliminary 
sections, such as the abstract, table of contents, or acknowledgements. 
Then you can use the . ++B macro to begin the bibliography at the end 
of the document. You will have to rearrange the document physically 
after printing to place the preliminary sections at the beginning. 
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Type 


Form 


Explanation 


macro 


.+c[T] 


Print chapter heading, where T is the 
name of the chapter. If T is omitted, the 
chapter page is printed with no heading. 


macro 


.++P 


Print preliminary section of paper with 
lower case Roman numeral page 
numbers. 


macro 


.++B 


Print the bibliographic section of the 
paper. 



13.2.3 me Thesis format 

The . th macro sets up the headers, footers, margins, and spacing of 
the formatter to format a thesis according to the rules established at the 
University of California at Berkeley. The correct headers, footers, 
margins, and spacing are set up. 



Type 



Form 



Explanation 



macro 



,th 



Set up Berkeley thesis format. 



14. Changing fonts 

You can use the following macros to emphasize words or groups of 
words. Typewritten or line-printed material is usually emphasized with 
underlining. Typeset and typeset-quality material is emphasized with 
boldface or italics. 

In itis, the . B and . I macros produce boldface and italics, 
respectively, with t rof f and underlining with nrof f . In me, use . b 
for bold and . i for italics. There are several ways of using these 
macros in your text. 

In ms, . B or .1 can be followed by RETURN, and all subsequent text 
will be printed in boldface or italics. This usage must be terminated by 
a . R command, indicating that printing should return to roman, as 
follows: 
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.B 

This text will be printed in boldface. 

.R 

In ms, . B or .1 can be followed by a single word on the same line. 
The same is true in me, where . b or . i can be followed by a single 
word. In that case, only that word is emphasized and no . R is needed 
for the ms text: 

.B word 

In both macro packages, the macros for boldfacing and italicizing can 
be followed by a group of words on the same line. These must be 
enclosed in double quotes. Again, only those words are emphasized 
and no . R is needed. For example, in ms you could use: 

.B " group-of-words" 

The underline macros, . UL (ms) and . u (me), apply only to text 
processed with trof f . They underline one word at a time. If multiple 
word underlining is desired, you must enter individual underlining 
commands for each word. Enclosing multiple words in quotes does not 
work. For example, in ms you could use: 

text 

.UL wordl 
.UL word2 
.UL words 
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Type 


Form 


Explanation 


inms: 
macro 


.BM 


Print X in boldface (t rof f only). If x 
is not present, print all subsequent text 
in boldface. 


in me: 
macro 


.bW 


Print X in boldface (t rof f only). 


inms: 

macro 


.iW 


Print X in boldface. If x is not present, 
print all subsequent text in italics. 


in me: 

macro 


.iW 


Print X in italics. 


inms: 
macro 


• R 


Return to roman font. 


inms: 

macro 


• UL X 


Underline x (t rof f only). 


in me: 

macro 


.MX 


Underline j: (t rof f only). 



14.1 Changing the string point size 

In ms, three macros are provided to control the relative size of trof f 
type. . SM and . LG decrease and increase point size by 2 points, 
respectively, and both can be repeated to increase the effect. In me 
there is only the one . sm macro to set a word or phrase in a smaller 
point size. The ms . NL command restores point size to the default. 
These macros are used for temporary size changes for a single word or 
a small group of words. (See "Setting Point Size and Vertical 
Spacing" to change absolute point size.) 
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Type 


Form 


Explanation 


inms: 






macro 


• SM 


Decrease point size by 2. 


in me: 






macro 


. sm 


Decrease point size by 2. 


inms: 






macro 


• LG 


Increase point size by 2. 


inms: 






macro 


.NL 


Set point size back to normal. 
Initial value: 10 



15. Changing and removing the date in ms 

When you use nrof f with the ms macros, the current date is printed 
at the bottom center of every page. With both nrof f and t rof f , 
when you use . RP format (see "Paper Styles") the current date is 
printed on the cover sheet of the document. The following macros are 
provided to change these default features. 

15.1 Changing the date 



Type 


Form 


Explanation 


macro 


.DA [x] 


In trof f print the current date at the 
bottom of each page (in nrof f this is 
the default). Argument x replaces the 
current date with a different value. 
(The current date is kept in string 
register \* (DY.) 



15.2 Removing the date 

Use the . ND macro to suppress printing of the date. If you add a date 
as an argument, that date is printed on the cover sheet in released paper 
format. 
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Type Form Explanation 

macro .nd [x] Suppress printing of the date. If a date 

is given as an argument, it is printed on 
the cover sheet in . RP format 



16. Drawing boxes 

You can draw a box around a single word or a group of words with the 
box macros. 

16.1 Boxing a word 

Use the . BX command in ms or the . bx command in me to draw a box 
around a single word. The word to be boxed is entered as an argument 
to the macro. For example, in ms: 

.BX word 



Type 


Form 


Explanation 


inzns: 

macro 

inxne: 

macro 


.BX X 

.bx 


Draw a rectangular box around a word, 
where x is any word. 

Draw a rectangular box around a word, 
where x is any word. 



16.2 Boxing a block of text 

16.2.1 Boxing a block of text in ms 

You can draw a box around a group of words with the . Bl and . B2 
macros. Text to be boxed is entered on the line following the . Bl. 



Type 



Form 



Explanation 



macro 
macro 



Bl 
B2 



Begin boxed text. 
End boxed text. 



16.2.2 Boxing a block of text In me 

You can box a phrase in me by grouping the arguments to the . bx 
macro in double quotes, but you can't box more than one line at a time. 
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17. Checking your work 

You can check your file for formatting errors with the checknr 
program, checknr examines your file and reports any unrecognized 
macros or unbalanced macro constructions. For example, it will find 
any . DS commands that are not terminated with . de, and it will verify 
that each . RS command has a corresponding . RE command. 

To run checknr, enter the command 

checknr file 

Any discrepancies are written to the standard output. Or, if you prefer, 
you can direct the output from checknr to a file so you can examine 
it later: 

checknr file > output-file 

For more detailed instructions on using this program, refer to the 
checknr(l) in A/UX Command Reference. 

18. Using nrof f /trof f commands in ms 

The ms macro package was designed to meet most text processing 
needs, making it unnecessary to learn the details of the complicated 
nrof f /trof f formatting language. However, you can use 
nroff/troff commands in conjunction with the ms macros without 
losing the benefits and simplicity of using a macro package. 

In addition to the . nr and . ds commands used to define number and 
string registers, you can use the following nroff/troff commands 
in a file processed with the ms macros: 

.cen Center n lines of text. If n is omitted, only the line 
following is centered. 

. sp n Print n blank lines. If n is omitted, one blank line is 
printed. 

. b r Start a new output line. 

. bp Begin a new page. 

. pi n Set the page length to n. 

. 1 s « Set the line spacing to n. 
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.na No adjust. Turns off right-margin justification. 

. ad Adjust both margins. 

Note that you can use . Is, . na, and . ad anywhere in your document; 
the remaining requests, however, must not appear until after the 
initializing macro (see "Sequence of Beginning Macros")- 

19. Creating your own macros 

You can create your own macro out of a sequence of nrof f /trof f 
commands and other defined macros. The basic procedure is to set up 
a definition string and then name the macro. Because ms uses 
uppercase macro names, it is probably a good idea to use ms custom 
macro names that are either a single lowercase letter or an uppercase 
letter followed by a lowercase letter. The opposite is true for me, 
where macros are already in lowercase. If you are using me you 
probably want to name your macros with uppercase letters. In me, 
avoid using TS, TH, te, eq, and en. 

19.1 Conventions used in this reference 

The following conventions are used to describe macro names: 

n digit 

X alphanumeric character 

All other characters are literals (characters that stand for themselves). 

Macro and string names are kept in a single internal table. Therefore, 
there must be no duplication among such names. Number register 
names are kept in a separate table. 

19.2 Defining a macro in me 

To define a macro in me, start the definition with . de XX, where XX is 
the name you wish to call the macro. List any requests, or other macro 
commands that will be included, then end the macro with . . on a 
separate line. Your macro will now be named XX. 

19.3 Format of names used by ms 

Macros are in the form x, xx, or xn (for example, macros .1, . pp, and 
.PI), and registers are in the form xx (for example, PO). 
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19.3.1 Names used by eqn/neqn and tbi 
The mathematical equation preprocessors, eqn and neqn, use 
registers and string names of the form nn. The table preprocessor, 
tbl(l), uses T&, T#, and TW, and names of the form 

X- x+ x\ "x "x #;c 

20. How ms formats 

20.1 Filling 

ms processes text by filling and adjusting the character input to fit the 
page dimensions and formatting instructions. Words are collected from 
the input and are placed on each output line until no more text will fit 
within the line length. The text fills the line. Spaces are inserted 
between words as necessary to bring the text exacdy to the right 
margin. Formatting macros then provide further instructions such as 
paragraph separation, top and bottom margins, footnotes, and headings. 
A break is any interruption of the filling or adjusting process, t rof f 
automatically skips to the next output line when a break occurs. 

The ms macros that cause a break are 

. AB Begin abstract. 

. Al Author's institution. 

.AU Author's name. 

. Bl Begin boxed text. 

. B2 End boxed text. 

. BD Block display (no keep). 

. CD Centered display (no keep). 

. CT Chapter title. 

. DE End display. 

. D S S tart standard display. 

. EN End equation. 

. EQ Start equation. 

. ID Indented display (no keep). 

. IP Indented paragraph. 
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. KE End keep. 

• KS Start keep. 

. LD Left-adjusted display (no keep). » 

. LP Left-block paragraph. 

. MC Begin multiple column text. 

. NH Numbered heading. 

. pp Standard paragraph. 

. QP Quote paragraph. 

. RE End right shift. 

. RS Begin right shift. 

. SH Unnumbered section heading. 

. TC Print table of contents. 

. TE End table. 

. TL Print centered title in boldface. 

.TS Start table. ^ 

. XA Additional index entry. ^ 

. XS Begin index entry. 

. IC Resume one-column printing. 

. 2C Begin two-column printing. 

21. Reference tables 
21.1 Macro summaries 

21.1.1 xas Macro summary 

Name Description 



AB 


Begin abstract. 


AE 


End abstract. 


AI 


Author's institution, 
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Name 


Description 


.AU 


Author's name. 


.B[x] 


Print X in boldface. If x is not present, print all 
subsequent text in boldface. 


.Bl 


Begin boxed text 


.B2 


End boxed text 


.BD 


Block display; center entire block. 


.BT 


Bottom title, printed at foot of page. 


.BX [x] 


Print jc in a box. 


.CD 


Centered display (no keep). 


.CT 


Chapter title. Page number is moved to register CF 



(thesis mode only). 

• DA [x] Print current date at the bottom of each page. With 

a date as an argument, uses that date in place of the 
current date. 



.DE 


End display. 


.DS [xy] 


Begin display with keep. 




;c=l indented 




x=L left adjusted 




x=C centered 




x=B block 




}'=amount of indentation 


.EF [' I' c'r'] 


Even footer. 


.ERi'l'c'r'] 


Even header. 


.EN 


End equation. 
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Name Description 

.EQ [xy] Begin equation. 

x=l indented 
x=L left adjusted 
x=C centered 
y=E equation label 



.FE 


. FS [x] 


• l[x\ 


• ID 


.i^ixy] 


.KE 


.KF 


.KS 


.LD 


.LG 


.LP 


.MC [xy] 


. ND [jc] 


. NH [x] 



End footnote. 

Start footnote, where x is a user-defined label. 

Print j: in italics. If jc is not present, print all 
subsequent text in italics. 

Indented display (no keep). 

Indented paragraph, where j: is a label and y is the 
indentation. 

End keep (static or floating). 

Begin floating keep. 

Begin static keep. 

Left-adjusted display (no keep). 

Increase point size by 2. 

Left-block paragraph. 

Print text in multiple columns, where x is the 
column width and y is the gutter width. 

Suppress printing of date in page footer, where x is 
the date on the cover sheet (released paper format). 

Begin numbered heading, where x is the heading 
level. Ifj:=0, level is reset to zero. 
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Name Description 

.NL Return point size to normal. 

Initial Value: 10 

.OF [' I' c'r'] Odd footer. 

.0H[' I' c'r'] Odd header. 

. P 1 Print header (including page number) on the first 

page. 

. PP Standard paragraph with the first line indented. 

. P T Page title, printed at the head of each page. 

. PX [no] Print index, no suppresses the title. 

. QP Quote paragraph, centered and indented 5 ens from 

both margins. 

. R Return to roman font. 

. RE End right shift. 

. RP [no] Begin released paper format, no suppresses the 

title on the first page. 

. RS Begin right shift; start relative indentation. 

. SH Begin unnumbered section heading, left adjusted 

and boldfaced. 

. SM Decrease point size by 2. 

. TA X Set tabs to x, where x is the number of ens. 

Initial value: increments of 5 ens 

. TC [no] Print table of contents, no suppresses the title. 

. TE End table. 

. TH End running table heading. 
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Name Description 

Print centered title in boldface 2 points larger. 

Thesis mode. 

Begin table. H indicates a multipage header. 

Underline x. 

UNIX trademark message. 

Additional index entry, x is the page number of the 
entry and y is the amount of indentation (in ens). 

End index entry. 

Exdented paragraph. 

Begin index entry, x is the page number of the 
entry andy is the amount of indentation (in ens). 

Resume one-column printing. 

Begin two-column printing. 

Begin reference. 

End unclassifiable reference. 

Classifiable reference. 
n=l journal article 
n=2 book 
n=3 book article 
«=4 report 



.TL 




• TM 




.TS 


[H] 


• UL 


x 


• UX 




.XA 


[xy] 


.XE 




.XP 




.XS 


[xy] 


.IC 




.2C 

1 _ 




. [0 




. [n 
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21 .1 .2 zne Macro summary 



Name Description 



.b ix] Prints in boldface. If ;c is not present, print all 

subsequent text in boldface. 

. be Begin new column. 

.bi [x] Prints in bold italics. Ifx is not present, print all 

subsequent text in bold italics. 

. bp Begin new page. 

. bx Print inside a box. 

. (b Begin block text. 

. ) b End block text. 

++B Print bibliography. 

. ce [x] Center x lines, x defaults to 1. 

. (c Begin centered block. 

. ) c End centered block. 

.+c T Print chapter with title r. 

. EN End equation. 

. EQ [X y] Begin equation. 

x=l indented 
x='L left adjusted 
x=C centered 
y=E equation label 

. f o Print footer. 

. (f Begin footnote. 
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Name Description 

. ) f End footnote. 

.in l+n] Indent n spaces, rt can be a negative number for 

left indent. 

. he Print header. 

.1 [x] Print;c in italics. If ;c is not present, print all 

subsequent text in italics. 

. ip [X y] Indented paragraph, where ;c is a label, and y is the 

indentation. 



.Ip 


Left-adjusted paragraph. 


. (1 


Begin list. 


.)1 


End list. 


.np 


Numbered paragraph. 


.nr 


Numbered register. 


•PP 


Standard paragraph. 


.++P 


Print preliminary part of paper. 


. (q 


Begin major quote. 


.)q 


End major quote. 


.r [x] 


Print X in roman. If x is not pre 




subsequent text in roman. 


.sh 


Print section heading. 


. sm 


Decrease point size by 2. 


• sp [n] 


Space down n. n defaults to 1. 


.TE 


End table. 
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Name 


Description 


• th 


Set up Berkeley thesis environment. 


.TH 


End running table heading. 


.ti[+/i] 


Temporarily indent n spaces, n can be a negative 
number for left indent 


.TS [H] 


Begin table. H indicates multipage header. 


.uh 


Unnumbered section heading. 


.Ul [X] 


Underline x. 


.xp 


Print index. 


. (x [xy] 


Begin index entry, x is the page number and y is 
the amount of indentation in ens. 


.)x 


End index entry. 


. (z 


Begin floating keep. 


.)z 


End floating keep. 


.Ic 


Resume 1 -column printing. 


.2c 


Begin 2-column printing. 



21.2 Number register summary 



Name Description 



mine: 

pp Standard paragraph point size. 

Initial value: 10 

sp Section header point size. 
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Name Description 

Initial value: 10 ( 

tp Tide page point size. 

Initial value: 10 

inzns: 

CF Center footer. 

Initial value: current date (nrof f only) 

CH Center header. 

Initial value: current page number surrounded by 
hyphens 

DD Display distance. 

Initial value: Iv in nrof f , .5v in trof f 

FF M Footnote format. 

jc=l Suppress superscripting of footnote label. 

x=2 Suppress indentation of first line of footnote / 

text. ^ 

jc=3 Footnote as indented paragraph. 
Initial value: 



FI 


Footnote indent. 
Initial value: 2 ens 


FL 


Footnote length. 
Initial value: 5.5i 


FM 


Footer margin. 
Initial value: li 


HM 


Header margin. 
Initial value: li 


LF 


Left footer. 


LH 


Left header. 
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Name Description 

LL Line length. 

Initial value: 61 

LT Title length. 

Initial value: same as LL (6i) 

PD Paragraph distance. 

Initial value: Iv in nrof f , 0.3v in trof f 

PI Paragraph indent. 

Initial value: 5 ens 

PO Page offset. 

Initial value: in nrof f ), ~li in trof f 

P S Point size. 

Initial value: 10 

RH Right header. 

Qi Quote paragraph indent. 

Initial value: 5 ens 

vs Vertical spacing. 

Initial value: 12v 

21.3 String summary 

You can use the following strings in your text files. 



Name 


Description 


inms: 




\*Q 


quote (" in nrof f , " in trof f ) 


\*U 


unquote (" in nrof f , " in trof f) 


\*_ 


dash (-- in nrof f , - in trof f ) 


\*(M0 


month 
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Name Description 



\*(DY 


day (current date) 


\** 


automatically numbered footnote 


\*' 


acute accent (before letter) 


\*A 


grave accent (before letter) 


\*- 


circumflex (before letter) 


\*, 


cedilla (before letter) 


\*: 


umlaut (before letter) 


\*~ 


tilde (before letter) 


in me: 




\*# 


delayed text 
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Chapter 6 
tbi Reference 



1. tbi: a table formatting program 

The tbi program is a document formatting preprocessor for trof f 
and nrof f . Tables consist of columns that can be independendy 
centered, right adjusted, left adjusted, or aligned by decimal points. 
Headings can be placed over single columns or groups of columns. A 
table entry can contain equations or consist of several rows of text. 
Horizontal or vertical lines can be drawn within the table, and any table 
or element can be enclosed in a box. 

The tbi program converts table formatting instructions into 
nrof f /trof f commands, and these processors do the actual 
formatting of the text. 

The following chapter shows you how tbi works and how to use it to 
obtain the output you desire. However, the best way to learn tbi is by 
studying the "Examples" section and creating your own practice 
exercises based on the samples provided. 

2. Using tbi 

2.1 Command line syntax 

tbi can be run on a simple table with the command 

tbi file I troff 

For more complicated use, where there are several input files and 
macro package commands (such as itim) as well as tables, the command 
would be 

tbi filelfile2file3 I troff -mm 

The files are processed in sequence, and then this data is passed on to 
the remaining processors. 

If a filename is not specified on the command line or if the filename 
given is a minus sign (-), tbi reads the standard input. 
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Using tbl with the nrof f formatter is similar to using it with 
trof f , but only certain hard-copy terminals can print vertical lines or 
boxed tables. 

For the convenience of those using line printers without adequate 
driving tables or post-filters, there is a special -TX command line 
option to tbl that produces output without fractional-line motions (see 
tbl(l) in A/UX Command Reference). 

The only other command line options recognized by tbl are the ms 
and the mm macros. These arguments are accepted by tbl, but it is 
usually more convenient to place them on the nroff/troff 
formatter portion of the command line. 

2.2 Running tbl with other A/UX preprocessors 

When pic, tbl, and eqn operate on the same file, pic is always 
called first: 

pic file I tbl I eqn | trof f 

If only eqn and tbl are present, tbl should be called first, eqn 
produces a larger expansion of the input, and it is faster and more 
efficient to execute it after tbl. If there are no equations within tables, 
either sequence works. But, if there are equations within tables, tbl 
must be called first or the output will be scrambled. 

When there are several input files containing tables, equations, and mm 
macros, the correct command sequence is 

tbl filelfile2file3 I eqn I trof f -mm 

If you also use the extended mathematical character set in 
/usr/pub/eqnchar (see Chapter 7, "eqn Reference"), the 
command reads 

tbl /usr/pub/eqnchar file I eqn | troff -mm 

3. Defining your table format 

The general format of tbl input in a document is 
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preceding text 
.IS 

global options ; 

column formatting instructions . 
table data 

.TE 

more text 

The global format line defines the overall format of the table. The 
column formatting Une defines the column aUgnment of the table 
entries. These specifications are preceded and followed by a table start 
( . TS) and table end ( . TE) command. The . TS and , te lines are then 
used by t rof f as command delimiters. 

If there isn't enough space on the page for a table, it is continued on the 
next page; however, boxes and vertical lines aren't drawn properly if a 
table is split between two pages. Enclosing your table in display 
macros keeps your table on one page (see Chapter 4, "mm Reference," 
and Chapter 5, ' 'ms Reference' ' for a discussion of the display 
macros). 

4. Global format options 

The global format line affects the format of the whole table. It consists 
of a single line of instructions and must immediately follow the . TS 
command. Option names must be separated by spaces, tabs, or 
commas, and the line must be terminated by a semicolon. 

The allowable options are 

Global option Description 



center 


Center the entire table 


expand 


Expand the table to the width of the current 
line length 


box 


Enclose the table in a box 


allbox 


Enclose each table entry in a box 


doublebox 


Enclose the table in a double-ruled box 
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Global option Description 



tab(x) Separate data items with character x instead 

of tab 

1 ine size n Increase line thickness (for example, box 
and allbox) to n-point size 

delim xx Specify that characters xc will be used as 

eqn delimiters 

Global options are discussed in the following sections. 

4.1 Table width and positioning 

The default positioning for a table produced by tbl is left adjusted. 
The center option places the table in the center of the page, as in the 
above example. The expand option spreads the table across the full 
width of the current line length of the page (see Figure 6-1). 

4.2 Drawing boxes 

There are three ways to globally specify boxed tables: box encloses 
the table in a single box, allbox encloses each item of the table in a 
box, and doublebox encloses the table in a double-lined box. Each 
is illustrated in "Examples." 

The tbl program tries to keep a boxed table on one page by issuing 
the appropriate . ne (need) t rof f command. This command is 
calculated from the number of lines in the table. If there are spacing 
commands embedded in the input, however, the . ne commands may 
be inaccurate. In that case, you can use trof f keep-release macros or 
can manually specify the . ne n command. If a multipage table is 
required, use the . TS H and . TH macros designed for this purpose 
(see "Multipage Tables and Variable Format"). 

4.3 Changing the thickness of your lines 

The line size n (where n is a point size) option permits you to 
specify a heavier line in your table than the default 10-point; for 
example, lines ize 30 produces 
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4.4 Setting a new tab character 

tbl uses the tab character to separate items of data. Because tabs are 
invisible, it is useful to reset the tab character to some other character 
that can be seen. You do this with the tab (x) option, where jc is a 
character you will not need in your table. For example, to change the 
tab character to a colon (:), use the following command: 

tab(:) 

4.5 Mathematical equations in your table 

When tbl processes columns of numbers it looks for a decimal point 
and attempts to split numeric format items into two parts (see 
"Numeric Columns are Different")- This feature interferes with the 
way eqn processes equations. The delim xc global option enables 
you to define eqn delimiters within your table which prevents this 
interference. 

Note: It is still better to avoid putting equations in numeric (n- 
style) columns. 



5. Column alignment: keyletters 

The format line(s) specifies column layout. It contains a "keyletter" 
for each column of the table that represents a particular column format 
instruction. 

Keyletter instructions may be entered in either upper or lowercase, and 
the last entry in the format section is always followed by a period. 

Keyletter Description 

1 Left adjusted column entry 

r Right adjusted column entry 

c Centered column entry 

n Numeric column entry; entries are aligned 

so the numbers line up at a decimal point 
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Keyletter Description 



Alphabetic column entry; entries are left 
adjusted and positioned so the widest entry 
is centered within the column 

Spanned heading; the entry from the 
previous column continues across this 
column 

Vertically spanned heading; the entry from 
the previous row continues down through 
this row 



5.1 Numeric columns are different 

When numeric column alignment (n-style) is specified, the rightmost 
dot ( . ) adjacent to a digit is used as a decimal point. If there is no dot 
adjoining a digit, the rightmost digit is used. If an alignment or 
alignment character isn't specified, the item is centered. However, the 
special nonprinting character string (\ &) can be used to override dots 
and digits or to align alphabetic data. This string lines up where a dot 
normally would (the \& disappears from the final output). 

In the following example, items shown in the "Input" column will be 
aUgned in a numeric column as shown in the "Output "column. 

input Output Comments 

13 13 (no alignment character) 

4.2 4.2 (aligned by decimal point) 

26.4.12 26.4. 1 2 (aligned by decimal point) 

abode fg abcdefg (centered) 

abcdefg\& abcdefg (\& as alignment character) 

7 4 9.12 749. 12 (aligned by decimal point) 

If numeric data is used in the same column with wider 1- or r-type 
table entries, the widest number is centered relative to the widest 
nonnumeric item; for example, 
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.IS 

center tab ( : ) ; 

1 1 

n n . 

shortest : longest entry 

13:13 

42,347.99:42,347.99 

0.5:0.5 

.TE 

will send the output 



shortest 


longest entry 


13 


13 


42,347.99 


42,347.99 


0.5 


0.5 



This is similar to alphabetic subcolumns (a -style) which are always 
slightly indented relative to left adjusted items. If necessary, the 
column width is increased to force this. 

5.2 How tbi reads your keyletter instructions 

The layout of keyletters in the format section represents the layout of 
the actual data in the table. For example, a simple three-column format 
might appear as 

CSS 

Inn. 

The first line of this table contains a centered heading spanned across 
all three columns (c s s). Each remaining line contains a left 
adjusted item in the first column followed by two columns of numeric 
data (1 n n). These specifications produce the following: 

Spanned Heading 

Item-1 34.22 9.1 
Item-2 12.65 .02 

Item-3 23 5.8 

Total 69.87 14.92 

Successive line formats separated by commas can also be given on the 
same line. For example, the format for the preceding example could be 
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wntten: 

c s s, 1 n n . 

Spaces between the keyletters are not required, but they can be helpful 
visually when setting up or changing a table format. Each line in the 
format section corresponds to a single Une of data. However, if there 
are more lines of data than there are format lines, the last format line 
corresponds to all following data lines up to the table end ( . TE) 
command or a table continue ( . T&) command (see "Adding New tbl 
Format Instructions in the Text"). 

5.3 Fine tuning your Iceyletter specification 

To permit further refinement of your table formatting instructions, 
keyletters can be followed by qualifiers that change the format and 
placement of the column entries, or change the size and shape of the 
columns. 

These qualifiers can be in any order, they can be upper or lowercase, 
and they need not be separated by spaces (except as indicated); for 
example, 

npl2w(2.5i)fl 6 

specifies a numeric column entry in 12-point type with a maximum 
width of 2.5 inches, in italic font and separated by 6 ens from the next 
column entry. 

5.3.1 Drawing horizontal lines 

A keyletter can be replaced by an underscore character (_) or equal 
sign (=) to specify a single or double horizontal line in place of the 
column entry: 

1_1 

If an adjacent column contains a horizontal line or if there are vertical 
lines adjoining this column, the horizontal line is extended to meet 
nearby lines. If any data entry is provided for this column, it is ignored 
and a warning message is printed. (See Figure 6-7.) 

5.3.2 Drawing vertical lines 

A vertical bar ( | ) may be placed between keyletters to cause a vertical 
line between the corresponding columns of the table (see Figure 6-1). 
A vertical bar to the left of the first keyletter or to the right of the last 
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one produces a line at the edge of the table. If two vertical bars appear 
between keyletters, a double vertical line is drawn; for example, 

I 1 I 1 1 I 

5.3.3 Column spacing 

A number may follow the keyletter to indicate die amount of separation 
between this column and the next column; for example, 

n6 n 

The number specifies the separation in ens. One en is about the width 
of the letter ' *n." More precisely, an en is the number of points equal 
to half the current type size. If the expand option is used, these 
numbers are multiplied by a constant, making the table as wide as the 
current line length. The default column separation number is 3. If the 
separation is changed, the largest space commanded is assumed. 

5.3.4 Vertical spacing 

A keyletter followed by v and a number indicate the vertical line 
spacing within a multiline table entry. The number may be plus or 
minus (+ or -), in which case it is taken as an increment or decrement 
from the current vertical spacing; for example, 

cv+2 

A column separation space value must be separated by blanks or some 
other specification from a vertical spacing command. This command 
has no effect unless the corresponding table entry is a block of text (see 
"Text Blocks: Multiline Entries"). 

5.3.5 Vertical spanning 

Vertically spanned items extending over several rows of the table are 
normally centered in their vertical range. If a keyletter is followed by 
t, any corresponding vertically spanned item will begin at the top line 
of its range; for example. 

It ct at 

5.3.6 Column widtli 

A keyletter followed by w and a value in parentheses specifies 
maximum column width; for example. 
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lw(2i) 

specifies a 2-inch column. 

If the largest element in the column is not as wide as the width value 
given after the w, the column is assumed to be that wide. If the largest 
element in the column is wider than the specified value, its width is 
used. The width is also used as a default line length for text blocks (see 
"Text Blocks: Multiline Entries"). 

Normal trof f formatter units can be used to scale the width value. 
The default value is ens, but inches also may be used. If the width 
specification is a unitless integer, the parentheses may be omitted. If 
another width value is given in a column, the last one controls the 
width. 

5.3.7 Equal-width columns 

A key letter followed by e indicates equal- width columns. All columns 
whose keyletters are followed by e or E are made the same width; for 
example, 

le ne 

5.3.8 Staggered columns 

A keyletter followed by u indicates that the corresponding entry is to 
be moved up one-half line. This makes it easy to have a column of 
differences between numbers in an adjoining column. 

Note: Staggered columns do not work with the allbox 
option. 

5.3.9 Font Changes 

A keyletter followed by f and a string containing a font name (such as 
R, I, or B) or font number (such as 1, 2, or 3) indicates that the 
corresponding column should be in a different font from the default 
font; for example, 

lf2 IfB 

specifies one column of italics and one column of boldface. 

All font names are one or two letters. A one-letter font name should be 
separated from whatever follows by a space or tab. 
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Note: trof f font change commands given within the table 
data override these specifications. 

5.3.10 Point Size Changes 

A keyletter followed by p and a number indicates the point size of the 
corresponding table entries. If the number is preceded by a plus or 
minus (+ or -) sign, the value is incremented or decremented from the 
current point size; for example, 

lp8 

If both a point size and a column separation value are given, one or 
more blanks must separate them. 

5.3.1 1 Zero-width items 

A keyletter followed by a data item is ignored in calculating column 
widths. This may be useful in allowing a long heading to run across 
adjacent columns where a spanned heading would be inappropriate. 

5.3.12 Default coiumn spacing 

Column descriptors missing from the end of a format Une are assumed 
to be left adjusted. The longest line in the format section, however, 
defines the number of columns in the table. Extra columns in the data 
are ignored. 

6. Refining your format 

Table data is entered immediately following the format line. Each line 
of the table is entered as one line of data. Very long input lines can be 
broken up, however, by ending the first part of the input line with a 
backslash (\) or by using text blocks (see "Text Blocks: Multiline 
Entries"). When using the backslash, the line following it is combined 
with the preceding line (the backslash vanishes). 

6.1 Tabs separate data in columns 

Data for each column is separated by a tab or by whatever character 
has been specified in the tabfx) global option. 

6.2 Inserting tro££ commands in your table 

t rof f commands can be interspersed with table data to provide 
further refinement and definition of the table output. 
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An input line beginning with a dot and followed by anything but a 
number is assumed to be a command to trof f and is passed through 
unchanged, retaining its position in the table. For example, an . sp 
command can be used within a table to change the spacing between 
rows. 

Point size and font changes may also be made within the table data. 
trof f commands (such as \f I, \s+2, and so forth) entered within 
the table override tbl column formatting instructions. 

6.3 Text blocks: multiline entries 

In order to include a block of text as a table entry, precede it by tab and 
T { . Enter text on a new line, and terminate it with "t { " ; for example, 

previous text^ni 

block of 

text 

T} 

where " I is a tab character or other character defined as a tab character 
in the global specification of the table. The begin delimiter (T { ) must 
be followed by a new line, and the end delimiter (T } ) must begin a 
new line; however, additional columns of data may follow after a tab 
on the same line. Text is pulled out from the table, processed 
separately by the formatter, and replaced in the table as a solid block. 

Note: Limits in the trof f program will be exceeded if 30 or 
more text blocks are used in a table. This produces diagnostic 
messages such as "too many string/macro names" 
or "too many number registers." 

If no line length is specified in the block of text or in the table format, 
the default is used: 

/xc/(«+l) 

where / is the current line length, c is the number of table columns 
spanned by the text, and n is the total number of columns in the table. 

Other parameters such as point size or font used in formatting the text 
block are 
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• those defined for your whole document (including the effect of 
the .TS macro) 

• any table format specifications of size, spacing, font, and column 
keyletters 

• t rof f commands within the text block itself (commands within 
the table data but not within the text block do not affect that 
block) 

6.4 More ways to draw lines 

In addition to specifying lines using the keyletter system, tbl also 
permits line specification within the data section. 

6.4.1 Full width horizontal lines 

If an input line contains only an underscore character Q or equal sign 
(=) on a line by itself, a single or double line is drawn that extends the 
full width of the table; for example, 

• TS 

global options ; 

column formatting instructions . 

data 

data 

.TE 

6.4.2 Single-column width lines 

If an individual table entry contains an underscore character O or 
equal sign (=), a single or double line is drawn that extends the full 
width of the column. Such lines are extended to meet horizontal or 
vertical lines adjoining this column. 

To obtain these characters (_ and =) explicitly in a column, they should 
be preceded by a \ & or followed by a space before the usual tab or 
newline character. 

An input table entry that contains only the string \_ is assumed to be a 
single fine as wide as the text in the column. It differs from the above 
single-column line in that it is not extended to meet adjoining lines. 
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6.4.3 Character repetition 

An input table entry containing only the string \Rjc, where x is any 
character, is replaced by repetitions of that character as wide as the 
data in the column. This sequence of characters is not extended to 
meet adjoining columns. 

6.4.4 Vertical spanning 

An input table entry containing only the character string \ " indicates 
that the table entry immediately above spans downward over this row. 
It is equivalent to the key letter ' " '. 

7. Multipage tables and variable format 
7.1 Multipage tables with repeated headings 

You can print tables on more than one page with tbl, and if you use 
the mm and ms macros, you can produce multipage tables with repeated 
headings. Begin your table with this macro: 

.TS H 

After you enter your heading text, input the macro . TH. Text that 
precedes the . th is placed at the top of each page of the table. The 
remaining lines of the table are placed on additional pages as required; 
for example, 

• TS H 

global options ; 

column formatting instructions . 

heading text 

.TH 
data 

.TE 

If you use the mm macro package, the . TH macro can take the 
argument N. This causes the table header to be printed only on the first 
line on a page. This option is used when it is necessary to build long 
tables from smaller . TS H/ . TE segments; for example, 
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• TS H 
global options ; 

column formatting instructions . 
heading text 

.TH 

data 

.TE 

• TS H 

global options / 

column formatting instructions . 

heading text 

.TH N 

data 

.TE 

Note: This is not a feature of tbl but of mm and can be used 
only with the mm macro package. 

Although any number of lines may be present in a table, only the first 
200 lines are used in setting up the table. A multipage table may be 
arranged as several single-page tables if this proves to be a problem. 

7.2 Adding new tbl format instructions in the text 

The table continue command ( . T&) resets column parameters. It is 
used to specify tables with groups of rows containing identical formats. 
Each group is different, but within a group, the format is the same. 

Table specifications are split into groups (separated by . T&), and each 
set of instructions specifies the format of each group. (See Figure 6-5.) 

The . T& command is recognized only within the first 200 lines of a 
table and does not change global options, the number of columns, the 
spacing between columns, or the selection of equal- width columns. 

An example of such table input is 
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.TS 




box 


expand; 


c s 


s 


1 1 


1. 


data 




.T& 




1 S 


s 


c c 


c . 


data 




.T& 




1 1 


1. 


data 




.TE 





Using this procedure, each data line can be located close to its 
corresponding format line. 

8. Restrictions 

Input to tbl is subject to the following restrictions: 

• The tbl program accepts up to 35 columns; the actual number 
that can be processed may be smaller depending on the 
availability of t rof f number registers. 

• The keyletters n and a may not be used in the same column. 

• Computation of column width is restricted to the first 200 lines of 
data. 

• Table continue commands ( . T&) apply only the first 200 lines of 
a table. 

• Staggered column entries and multipage tables do not work with 
the global option allbox. 

• When calculating column widths, all entries are assumed to be in 
the font and point size in use when the . TS request was 
encountered. However, font and point size specifications can be 
changed within the data section (as in entry \s+3data\ s 0). 

• When processing a file which contains tables and equations, tbl 
should always be called before eqn. 
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• Number register names used by tbl must not be used within 
tables. These include 2-digit numbers from 31 to 99 and strings 
of the form 4jc, 5x, #x, x+, x \, "x, and x-, where x is any 
lowercase letter. The names ##,#-, and # '^ should also be 
avoided. (When assigning eqn delimiters in a table, the symbols 
## must never be used.) 

• Multipage tables should not be boxed. 

• No more than 30 text blocks can be used in a table. This number 
may be smaller if the individual text blocks are long. 

• Table width is defined in number register TW before the . te 
macro is invoked, and may be used to expand that macro. 

9. Examples 

Figures 6-1 through 6-10 are included to show tbl input and output 
information and to illustrate the basic concepts of the tbl program. 
Although each figure has a title naming certain options or features, 
other uses of tbl can be learned from them as well. For instance. 
Figure 6-5 shows the use of additional command lines and also 
specifies bold type print in the format area. Studying these examples 
will help you learn how to use the tbl program much more easily than 
by simply reading the written explanations. 
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Figure 6-1 . Table using the expand option 
Input: 

.TS 

expand box center tab ( : ) ; 

c s 

111. 

Menu 

Monday : Fish 
Tuesday : Tostada 
Wednesday : Tuna salad 
Thursday : Spaghetti 
Friday : Chicken 
.TE 



Output: 



Menu 


Monday 


Fish 


Tuesday 


Tostada 


Wednesday 


Tuna salad 


Thursday 


Spaghetti 


Friday 


Chicken 
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Figure 6-2. Table using the allbox and center options 



Input: 

.TS 

allbox center tab(:) ; 

CSS 

c c c 

n n n . 

Paradox common stock 

Year : Price : Dividend 

1971:41-54:$2.60 

2:41-54:2.70 

3:46-55:2.87 

4:40-53:3.24 

5:45-52:3.40 

6:51-59: .95* 

.TE 

.ce 

* (first quarter only) 



Output: 



Paradox common stock 


Year 


Price 


Dividend 


1971 


41-54 


$2.60 


2 


41-54 


2.70 


3 


46-55 


2.87 


4 


40-53 


3.24 


5 


45-52 


3.40 


6 


51-59 


.95* 



(first quarter only) 
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Figure 6-3. Table using the vertical bar keyletter feature 

Input: 

.TS 

center box tab ( : ) ; 

cB s s 

cl I cl I cl 

1 I 1 I n . 

Major New York bridges 

Bridge : Designer : Length 

Brooklyn: J. A. Roebling: 1595 
Williamsburg: L. L. Buck: 1600 

7:1380 

Triborough :0. H. Ainmann:_ 

: :383 

Bronx Whitest one :0. H. Ammann : 2 3 
Throgs Neck:0. H. Ammann: 1800 
.TE 



Output: 



Major New York bridges 


Bridge 


Designer 


Length 


Brooklyn 
Williamsburg 


J. A. Roebling 
L. L. Buck 


1595 
1600 


Triborough 


0. H. Ammann 


1380 


383 


Bronx Whitestone 
Throgs Neck 


O. H. Ammann 
0. H. Ammann 


2300 
1800 
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Figure 6-4. Table using horizontal lines in place of keyletters 
Input: 



TS 



center doublebox tab ( : ) ; 




L L L 




L L _ 




L L 1 LB 




L L _ 




L L L . 




January : February : March 




June: July: MONTHS 




October : November : December 




.TE 




Output: 








January February 


March 




April May 










June July 


MONTHS 




August September 










October November 


December 
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Figure 6-5. Table using additional command lines 



Input: 



.TS 

center box tab ( : ) ; 
cfB s s s . 
Composition of foods 



.T& 






c 1 c s s 






c 1 c s s 






c 1 c 1 c 1 c . 






Food: Percent by weight 


\^: 






\ " : Protein : Fat : Carbo- 


- 


\ ^ : \ ^ : \ -^ : hydrate 






.T& 






1 1 n 1 n 1 n . 






Halibut: 18. 4: 5. 2: 


... 




Lima beans : 7 . 5 : .8 


:22 





Mushrooms : 3 . 5 : . 4 : 


6.0 




.TE 







Output: 



Composition of foods 


Food 


Percent by weight 


Protein 


Fat 


Carbo- 
hydrate 


Halibut 
Lima beans 
Mushrooms 


18.4 
7.5 
3.5 


5.2 
.8 
A 


22.0 
6.0 



6-22 



A/UX Text Processing Tools 



Figure 6-6. Table using text blocks 



Input: 



.TS 

center allbox tab ( : ) ; 

cf I s s 

clw(li) clw(1.3i) clw(1.3i) 

111. 

New York area rocks 

Era : Formation: Age (years) 

Precambrian: Reading :>1 billion 

Paleozoic :Manhattan: 400 million 

Mesozoic :T{ 

Newark Basin, incl. Lockatong 

T} :200 million 

Cenozoic: coastal Plain:T{ 

On Long Island 30,000 years; 

Cretaceous sediments redeposited 

by recent glaciation 

T} 

.TE 

Output: 



New York area rocks 


Era 


Formation 


Age (years) 


Precambrian 


Reading 


>1 billion 


Paleozoic 


Manhattan 


400 milUon 


Mesozoic 


Newark Basin, incl. 
Lockatong 


200 million 


Cenozoic 


Coastal Plain 


On Long Island 30,000 
years; Cretaceous 
sediments redeposited 
by recent glaciation 
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Figure 6-7. Table using eqn delimiters 



Input: 



• TS 

center delim $$ tab ( : ) box ; 

cpl2b I c I c 

1 I c I c . 

1:$ rho $:$ sigma $ 

$ omega sub 1 $ : $ i over 2 $ : $ x sub i $ 

$ pi sub 2 $ : $ i over -2 $ : 

$ theta sup 1 = omega sub 3 $ : $ i over 2 $ : $ rho $ 

$ lambda sub 2:0 : $ x + y over 2 $ 
.TE 

Output: 



1 


p 


<T 


COi 




Xi 


^2 


i 

-2 





01=(O3 




P 


u 





x+^ 
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Figure 6-8. Table using horizontal lines in place of data 

Input: 

.TS 

center tab(#) delim $$ ; 

c c c I c . 

$P$#$Q$#$R$#$P ~ cap ~ ( wig Q ~ cup ~ R )$ 

T#T#T#T 

T#T#F#F 

T#F#T#T 

T#F#F#T 

F#T#T#F 
.TE 



p 


Q 


R 


P 


n(~5u/?) 


T 


T 


T 


T 


T 


T 


F 


F 


T 


F 


T 


T 


T 


F 


F 


T 


F 


T 


T 




F 
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Figure 6-9. Table showing the versatility of the tbi program 



Input: 



• TS 

center tab ( : ) 
1 c c c 1 
c 



\(da 



1 
c 
1 
1 
1 
c 
1 . 

\(da 



I 1 



I c I 1 



lex: :yacc : 

\(da::\(da 
Input \ (->:yylex: \ (->:yyparse : \ (-> Output 
.TE 



Output: 



lex 



i 



Input — > yylex 



—^ 



i 



yacc 



i 



yyparse 



-^ Output 
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Figure 6-10. Table showing font changes 



Input: 



• TS 

center box tab ( : ) 
cB I cB I cB 
cfl I cf3 I cf2 . 
Roman : Bold : Italic 

a : a : a 

b : b : b 

c : c : c 

d : d : d 

e : e : e 

.TE 



Output: 



Roman 


Bold 


Italic 


a 


a 


a 


b 


b 


b 


c 


c 


c 


d 


d 


d 


e 


e 


e 
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1. eqn: a mathematics formatting program 

The eqn program is a mathematical equation formatting preprocessor 
for trof f and nrof f . It was designed to be easy to learn and use. 
Its language has few rules, and even fewer exceptions, and can be 
learned very quickly. It interfaces directly with trof f , so 
mathematical expressions can be embedded in the running text of a 
manuscript, and the entire document can be produced in one process. 

Typical mathematical expressions require point size and font changes, 
positioning, line drawing, and other functions to print according to 
mathematical conventions. In the eqn program these are done 
automatically; eqn converts mathematical input into trof f 
commands and the resulting output is passed directly to the formatter 
for further processing. 

This chapter shows you how to use eqn. Examples are provided to 
illustrate its syntax and rules of grammar. Study these examples and in 
a very short time you should be able to produce typeset-quality 
mathematical text. 

2. Using eqn 

eqn needs no special keys to enter even the most complicated 
equations. Subscripts and superscripts are printed automatically in the 
appropriate size and font. Fraction bars are made the right length and 
positioned at the correct height. Output may be produced either on a 
typesetter, a laser printer, or on a terminal with forward and reverse 
half-line motions. 

2.1 Command line syntax 

To produce typeset-quality mathematical text, use the following 
command: 

eqn file \ troff 
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Any trof f options (such as mm) are located following the trof f 
formatter part of the command: 

eqn file \ trof f -mm 

An nroff -compatible version of eqn (neqn(l)) can be used with 
hardcopy terminals that have half-line forward and reverse capabilities. 
The input language is identical, but some things will not look as good 
because these terminals do not provide the same variety of characters, 
sizes, and fonts. However, the output is usually adequate for 
proofreading. 

To print equations on one of these devices, use the command 

neqn file \ nroff 
or 

neqn file \ nroff -1x 
where x is the terminal type being used. 

2.2 Using eqn with other A/UX preprocessors 

When eqn operates on the same file as the other AAJX preprocessors, 
pic and tbl (see Chapter 8, "pic Reference" and Chapter 6, "tbl 
Reference"), pic should be called first: 

pic file I tbl I eqn | troff 

If only eqn and tbl are present, tbl precedes eqn: 

thlfile I eqn | troff 

eqn produces a larger expansion of output than tbl, and it is faster 
and more efficient to produce the table first and the equation last. The 
order is optional, however, unless there are equations within tables, in 
which case tbl must be called before eqn or the output will be 
unreadable. 

2.3 Greel< ietters and mathematical symbols 

eqn knows the Greek alphabet and most mathematical symbols and 
mathematical names. For example, the input 
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• EQ 
size +2 

{e sup {i delta t}} 
.EN 

produces the output 

Braces can also occur within braces if necessary. For example, the 
statement 

• EQ 
size +4 

{e sup {i pi sup {rho +1}}} 
.EN 

generates 

Each string of characters (delimited by spaces, tildes, carets, or tabs) is 
compared with a symbol table. If it finds the string contained there, it 
substitutes the t rof f translation of that string. Digits, parentheses, 
brackets, punctuation marks, and the following mathematical words are 
converted to roman font: 

min 



sin 


cos 


tan 


arc 


max 


lim 


log 


In 


exp 


Re 


Im 


and 


if 


for 


det 



Other strings are converted to italic font. In the previous example, pi 
and rho become their Greek equivalents (tu and p). Parentheses, 
digits, and operators are also produced in roman font. 

A common error is to type f (pi ) without leaving spaces on both sides 
of the pi. Without spaces, eqn does not recognize pi as a special 
word, and it appears as f (pi) in the output instead of /(tt). 

The only way eqn can deduce that some sequence of letters is special 
is if that sequence is separated from the letters on either side of it. This 
can be done by surrounding a special word by ordinary space, tab, or 
newline characters. Special words can also be emphasized by 
surrounding them with tildes or carets. The following: 
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.EQ 

x~=~2~pi~int~sin~ (~omega~t'') 

.EN 

is much the same as the previous example, except tildes separate words 
like sin, omega, and so forth, and also add an extra space in the 
output per tilde. The output of this example is 

j:=27cJsin(coO 

Tables 7-1 and 7-2 at the end of this chapter provide a complete list of 
the mathematical characters recognized by eqn. 

2.4 Additional symbols 

Four-character trof f names can also be used to specify any 
characters eqn does not recognize; for example, \ (pi for the + sign 
and \ (mi for the - sign. (See Chapter 3, "nrof f /trof f 
Reference" for a complete list of trof f character codes.) 

Additionally, the file /usr/pub/eqnchar contains nrof f and 
trof f definitions of several more mathematical symbols. (See Table 
7-3 at the end of this chapter.) These definitions must be enclosed 
within eqn delimiters in order to be processed correctly. 

For users who are experienced with trof f motion commands and 
string definitions, almost any mathematical character can be defined. 
Studying the definitions contained in usr/pub/eqnchar will give 
you a good idea of how this is done (see eqnchar(5) in AIJJX 
Programmer' s Reference). 

Note: When you are making your own character definitions, it 
is easier if you use a line gauge from a graphics supply store to 
gauge the appropriate size changes and vertical and horizontal 
tr off motions. 

2.4.1 Using /usr/pub/eqnchar 

To process a document containing the extended mathematical set 

(/usr/pub/eqnchar), you must include this file in your command: 

eqn /usr/pub/eqnchar file I troff 
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Or, if you have also included tables in your text: 

tbl /usr/pub/eqnchar file | eqn | troff 

You may substitute neqn and/or nrof f in both of these commands if 
your output device requires it. 

2.5 Command delimiters 

Mathematical expressions are entered by beginning and ending each 
equation with the delimiters . EQ and . EN as follows: 

.EQ 
equation-specifications 

• EN 

2.6 Displayed equations 

A displayed equation is printed as a block, preceded and followed by 
half a vertical space (one blank line). It is specified with the nun display 
macro: 

.DS 

• EQ 
equation-specifications 

.EN 
.DE 

By default, a displayed equation using mm is left adjusted. Placement 
options (centered, indented, or right) are provided, however, that 
override these defaults. (See Chapter 4, "mm Reference," for a full 
discussion of the display macros.) 

For example, when using mm, the input 

• DS I 
.EQ 

X = f ( y over 2 ) + y over 2 

.EN 

.DE 

produces an indented equation 
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A centered equation can be produced with the following input: 

.DS C 

.EQ 

X sub i = y sub i 
.EN 
• DE 

The resulting equation will be centered on the page: 

Xi=yi 

If you are not using a macro package to format your document, you can 
still manipulate the placement of equations within text. To obtain a 
centered equation in a document without using ms or mm, enter the 
following: 

.ce 

.EQ 

X sub i = y sub i 

.EN 

2.7 In-line equations 

An in-line equation is printed within the text of your document. Like a 
displayed equation, it must be enclosed in delimiters, but instead of the 
. EQ/ . EN sequence, you define a character to be the delimiter. 

The most common character chosen to delimit in-line equations is the 
dollar sign ($), which is defined at the beginning of the text file by 
entering the following: 

.EQ 

delim $$ 
.EN 

These characters are then recognized by eqn in the subsequent text as 
delimiters and any text between them will be treated as an equation. 
For example, the input 

This is an example of an in-line equation 
$ X sub y + y = z $ using delimiters. 

would send this as output: 
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This is an example of an in-line 
equation Xy +3^=7 using delimiters. 

Producing something like 7-ray is easy using the in-line equation, 

$ gamma $-ray 

eqn will try to keep the text between the delimiters on one line, but if 
the equation is very long, trof f will break it based on the spacing of 
characters, not mathematical logic. This can produce awkward and 
inaccurate spacing, but you can prevent this by dividing the in-line 
equation into sections: 

$x+y=$$ (c sub d ) $ $ + pi $ 

To turn off the delimiters so the selected character can be used as text, 
enter the following into your file: 

.EQ 

delim off 
.EN 

Thereafter, eqn will no longer recognize the delimiter symbol. 

The following should be observed when using the in-line equation 
format: 

• Do not use braces, tildes, carets, or double quotes as delimiters as 
these have special significance to the . EQ and . EN macros. 

• t rof f font changes must be closed before in-line equations are 
encountered. 

3. Specifying equations 

An equation is specified by numeric items and mathematical operators. 
Each of these components must be separated from the others according 
to specific item separation conventions. For example, in the expression 

V52 

which was produced with the notation 

sqrt 5 sup 2 

sqrt and sup serve as operators and the spaces between these 
keywords and the arguments are item separators. 
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3.1 How spaces are interpreted during input 

Spaces and newline characters are used by eqn to separate pieces of 
input; they do not create space in the output. For example, the input 

• EQ 

X = y 

+ z + 1 
.EN 

produces the output 

x=y+z+l 

Each distinct entity within eqn must be delimited by blank spaces. If 
items are not separated properly, eqn will interpret the expression 
incorrectly. 

3.2 Special cliaracters force output spacing 

Varying amounts of blank space can be forced into the output by 
several characters: 

• A tilde (~) gives a space equal to the normal word spacing in 
text. 

• A caret (') gives a half-space. 

• A tab character spaces to the next tab stop (tab stops must be set 
by trof f commands). 

Tildes, carets, and tabs also serve to delimit pieces of input. In these 
cases, blank spaces are optional. For example, the input 

• EQ 

x~ = ~y~ + ~z 

.EN 

produces the output 
X =y +z 

3.3 Using quotes 

Enclosing a string of characters in double quotes ("...") prevents eqn 
from interpreting any special meaning the string might ordinarily have. 

For example, to produce the expression 
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enter the following: 

• EQ 

"sqrt" 25 over pi 

.EN 

Omitting the quotes results in 

Quotes are used to force the printing of braces and certain eqn 
keywords that wouldn't normally be printed. For example, the input 

.EQ 

"{ alpha is the name for "~alpha" }" 

.EN 

prints 

/ alpha is the name for a) 

The " " construction is often used as a place-holder (or null item) when 
eqn requires something to satisfy its rules of grammar but when 
nothing is actually wanted in the output. 

For instance, eqn does not accept unmatched brackets, braces, or 
parentheses. However, the input 

.EQ 

left "" 
X over y 
right } 
.EN 

permits you to obtain only a right brace: 



3.4 Combining items witli braces 

Braces ( { } ) are used to keep multiple objects together in unambiguous 
groups, eqn interprets the items within a set of braces before applying 
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the next mathematical function. 

The end of a subscript or superscript is marked by a space, tilde, caret, 
or tab. If the subscript or superscript specification requires spaces 
within it, braces are used to mark the beginning and end. For example, 
the input 

.EQ 

size +2 

{e sup {i delta t}} 

.EN 

produces the output 

Braces can also occur within braces if necessary. For example, the 
statement 

.EQ 
size +4 

{e sup {i pi sup { rho +1}}} 
.EN 

generates 

A general rule is that a complicated string enclosed in braces can be 
used in place of a single character (such as x). The eqn program 
administers the appropriate formatting commands. In all cases, 
complete pairs of braces must be used (unless the null item 
specification is employed). Omitting one or adding an extra one 
produces an error. 

3.5 Equation labels 

An equation label is specified as an argument to the equation start 
delimiter ( . EQ): 

.EQ 1.5c 

a + b + c over abc = sqrt 25 

.EN 
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The equation label is printed in the right margin: 

^^^^^=^25 1.5c 

4. Entering equations 

4.1 Subscripts and superscripts 

Subscripts and superscripts are specified with the operators sub and 
sup. The words sub and sup must be surrounded by spaces. For 
example, this specification: 

• EQ 

X sup 2 + y sub k 
.EN 

produces the following expression: 

The eqn program makes the necessary point size changes and vertical 
motion adjustments and automatically returns to the original base line. 
Either a space or tilde marks the end of a subscript or superscript. 

Multiple levels of subscripts or superscripts are permitted, such as 
subscripted subscripts and superscripted superscripts. If the subscript 
follows the superscript, the items are grouped to the right as in the 
expression: 

produced with the input 

• EQ 
size +2 

{x sup y sub z} 

• EN 

However, if the subscript precedes the superscript: 

.EQ 

X sub z sup y 

.EN 

the items are printed one above the other: 
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4.2 Fractions 

Fractions are specified with the operator over. For example, the input 

• EQ 

a+b over c+d+e = 1 

.EN 

produces 

a+b _^ 

c+d+e 

The division line is positioned and made the correct length 
automatically. 

When there is both a fraction and a superscript in the same expression, 
eqn produces the superscript first. For example, the specification 

.EQ 

-b sup 2 over pi 

.EN 

produces 

n 

4.3 Square roots 

The square root symbol is produced by the operator sqrt. For 
example, the input 

.EQ 

sqrt 25 
.EN 

draws the simple expression 

With the more complicated 

.EQ 

X = {-b +- sqrt{b sup 2 -4ac}} over 2a 

.EN 
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eqn produces 



^_ -b±^b^-4ac 
^ 25 

4.4 Items with limits 

Summations, integrals, and similar constructions are specified with the 
operators from and to. 

Either from or to can be omitted, but if both are present, they must 
occur in that order. For example, the input 

.EQ 

sum from i=0 to {i = inf } x sup i 

• EN 

produces 

The second item (i = inf) is enclosed in braces because it contains 
spaces. Braces are not necessary for the lower part (i=0), however, 
because it contains no spaces. 

Other useful keywords that can replace the sum in the above example: 

prod int 

union max 

min lim 
inter 

Because characters before the from can be anything, the from - to 
construction can often be used in unexpected ways. The input 

.EQ 

lim from {n -> inf} x sub n =0 

.EN 

produces the output 

limjCn=0 

4.5 Diacritical marks 

Diacritics are produced with the following keywords: 



eqn Reference 7-13 



X 


dot 


X 


X 


dotdot 


x 


X 


hat 


X 


X 


tilde 


X 


X 


vec 


t 


X 


dyad 


It 


X 


bar 


X 


X 


under 


X 



An example of an expression using diacritical marks is 

• EQ 

X dot under + x hat + y dotdot 

+ X hat + Y dotdot = z+Z bar 

.EN 

which will send as output 

4.6 Oversized brackets 

To produce large brackets [ ] , braces { } , parentheses ( ) , vertical 
bars I I , floors [ J and ceilings \ ] that surround information that 
spans more than one line, use the keywords left and right: 



• EQ 

left { 
= left 
+ left 
.EN 

This produces 



a over b + 1 right } 
( c over d right ) 
[ e right ] 




EQ 



right floor 



left floor X over y 

<= left ceiling a over b ~~ right ceiling 

.EN 



produces 
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X ^ a 

yj- -^ 

The resulting brackets are made large enough to cover whatever they 
enclose. 

A right keyword cannot exist without a corresponding left. If the 
expression requires that the left be omitted, use the paired double quote 
null construction: 

.EQ 

left " " ... right ) 

.EN 

The left " " means a left "nothing," which satisfies the rules 
without hurting the output. 

4.7 Piling objects 

Large braces, brackets, parentheses, and vertical bars are often used 
with another facility that makes vertical piles of objects. It is specified 
by the operator pile. Elements of the pile (there can be any number) 
are centered one above another, at the right height for most purposes. 
The keyword above is used to separate the components; braces must 
surround the entire list. Elements of a pile can be as complicated as 
needed, even containing nested piles. 

Three other forms of pile exist: 

• Ipile makes a left adjusted pile. 

• rpile makes a right adjusted pile. 

• cpile makes a centered pile, just like pile. 

Vertical spacing between pieces is somewhat larger for Ipile, 
rpile, and cpile than it is for ordinary piles. For example, to get 



sign(x)^^ 



1 if x>0 

if x=0 

-1 if jc<0 



enter 
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.EQ 

sign (x) "•==~left "{" 

rpile {1 above above -1}~~ j' 

Ipile {if above if above if}~~ 

Ipile {x>0 above x=0 above x<0} 
.EN 

The left " { " construction makes a left brace large enough to 
enclose the rpile {...}, which is a right adjusted pile. The Ipile 
specifications left adjust the remaining components. 

4.8 Matrixes 

Matrixes are produced easily with eqn. For example, to specify an 
array such as 

yi y^ 

the following is entered: 

.EQ 
matrix { '' 

ccol { X sub i above y sub i } 

ccol { X sup 2 above y sup 2 } 
} 
.EN 

This produces a matrix with two centered columns. Elements of the 
columns are then listed as they are for a pile: each element is separated 
by the word above. The Icol or rcol keyword also can be used to 
left or right adjust columns. Each column can be separately adjusted, 
and there can be as many columns as desired. 

The reason for using a matrix instead of two adjacent piles is if the 
elements of the piles are not all the same height they will not line up 
properly. A matrix forces them to line up because it looks at the entire 
structure before deciding the spacing to use. 

Each column must have the same number of elements. To force each 

column to have the same number of elements, use the keyword i 

nothing which will give the construction the proper number of 

elements: 
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• EQ 

matrix { 

ccol { X above y sub 1 above z sup 2 } 
ccol { z above nothing above z sub 1 } 

} 

.EN 

produces 

X 2 

5. Precedence rules 

Each eqn operator is associated with a precedence; operations with 
higher precedence are performed before those with a lower precedence. 
For example, a superscript is defined as having a higher precedence 
than a fraction: 

.EQ 

X sup y over z 

.EN 

In the following example, the eqn operators are listed in order of 
increasing precedence. Operators on the same line have equal 
precedence. 

from to 

over sqrt 

sup sub 

size font roman italic 

bold fat 

up down back fwd 

left right 

dot dotdot hat tilde bar under vec dyad 

If an expression contains operators of equal precedence, the order in 
which these operators associate decides which operation is performed 
first. If the operators associate to the left, the leftmost operation 
precedes the rightmost operation. For example, sqrt and over have 
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equal precedence. In the expression 

K 

the sqrt is performed before the over. 

The following operations associate to the left: 

over sqrt left right 

All others group to the right. 

You can force a particular analysis by placing braces around 
expressions; for example, 

.EQ 

X sub 2 over y sub 3 + z sub 4 

.EN 

produces 

y3 

Changing the precedence with braces 

• EQ 

X sub 2 over {y sub 3 + z sub 4} 

.EN 

results in a different equation: 

X2 

y3+z4 
6. Definitions 

The eqn definition facility permits a user to define an equation or part 
of an equation 

define name ' ...' 

Henceforth, any occurrence of name within an eqn expression will be 
expanded into whatever is inside the quotes. 

Keywords like sup, sub, or over, or any eqn construction, may be 
included in a definition. For example, if the sequence 



7-1 8 A/UX Text Processing Tools 



.EQ 

X sub i sub 1 + y sub i sub 1 

.EN 

appears repeatedly throughout a document, you can save typing time 
by defining it: 

• EQ 

define xy 'x sub i sub 1 + y sub i sub 1' 
.EN 

This definition makes xy a shorthand for whatever characters occur 
between the single quotes in the definition. (Any character can be used 
instead of the quote to mark the beginning and end of the definition as 
long as it does not appear inside the definition.) After defining xy, the 
input 

.EQ 

"The definition xy now expands to read" ~ xy 

.EN 

produces 

The definition xy now expands to read xi+yi^ 

Although definitions can use previous definitions, as in 

• EQ 

define xi ' x sub i ' 
define xil ' xi sub 1 ' 
.EN 

an item cannot be defined in terms of itself; for instance, 

define X ' roman X ' 

Since x is now defined in terms of itself, problems will result. 
However, if this expression is used, the quotes protect the second x: 



fIV" f 



define X ' roman "X 

eqn keywords can be redefined with define. For example, you can 
specify "/"to mean over with the following statement: 



eqn Reference 7-19 



.EQ 

define / ' over ' 

.EN 

Symbols can be defined differently in neqn and eqn with the 
operators ndef ine and tdef ine. A definition made with ndef ine 
takes effect only when running neqn; when tdef ine is used, the 
definition applies only to eqn. (Names defined with the define 
facility apply to both eqn and neqn.) 

7. Equation alignment 

You can align a series of equations at some vertical position (such as 
an equal sign) with the operators mark and lineup. 

The word mark can appear only once in an equation. This designates 
the horizontal position for all subsequent input containing the keyword 
lineup. Any number of equations may be lined up following a single 
occurrence of mark. The place where lineup appears is aligned 
with the position of the previous mark. For example, the input 

.EQ 

x+y mark = z 

.EN 

.EQ 

X lineup = 1 

.EN 

produces 

x+y=z 
x=\ 

mark does not look ahead and anticipate the requirements of the 
subsequent lineup: 

.EQ 

X mark = 1 

.EN 

.EQ 

x+y lineup = z 

.EN 
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This specification will not work because there isn't enough room for 
the x+y part after the mark remembers where the x is. In order to 
correctly align the equations, the following input is necessary: 

.EQ 

X = mark 1 

.EN 

.EQ 

X + y = lineup z 

.EN 

This produces 

x=l 

x+y=z 

Note: The mark and lineup operations do not work with 
centered equations. 

7.1 Controlling local motions 

Although the eqn formatter tries to position things correctly on the 
paper, it occasionally needs fine tuning. 

The operators back n and f wd n are used to make small horizontal 
moves, where n is how far to move in 1/100's of an em (about the 
width of the letter "m"). For example, back 50 moves output back 
about half the width of an "m." 

Similarly, output can be moved up or down with the up n and down n 
operators. 

8. Changing the size and shape of fonts 

By default, equations are set in 10-point type with standard 
mathematical font conventions, but there are times when default 
assumptions are not desired. Thus, point size and font change 
commands are provided. 

8.1 Local changes 

Local point size changes are made with size n and local font changes 
with the roman, italic, bold, or fat operators. These changes 
affect only the string that immediately follows, then font or point size 
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reverts automatically to its previous settings. For example, the input 

• EQ 

bold X y 
.EN 

produces 

xy 

Braces are used if something more complicated than a single character 
is to be affected: 

.EQ 

bold {x y} z 

.EN 

produces 

xyz 

If fonts other than roman, italic, and bold are desired, use the font x 
statement (where x is a one-character trof f font name or number). 

Note: Since eqn is programmed for roman, italic, and bold 
fonts, other fonts may not give as good an appearance. 

The fat operation takes the current font and widens it by overstriking; 
for instance, 

.EQ 

A = fat {pi r sup 2} 

.EN 

produces 

Legal point size numbers that may follow size are 

6 7 8 9 10 11 12 14 
16 18 20 22 24 28 36 

The size can also be changed by a given amount: 
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size +2 

This makes the size two points larger. (See the example in 
"Combining Items With Braces.") 

8.2 Global changes 

If an entire document is to be in a nonstandard point size or font, it is a 
nuisance to write out a point size and font change for each equation. 
Accordingly, you can globally set point size or font changes which 
thereafter affect all equations. The following statements would appear 
at the beginning of any equation to set the size to 16 and the font to 
roman: 

.EQ 

gsize 16 
gfont R 

.EN 

Any of the t rof f font names may be used in place of R. The value of 
gsize can also be made a relative change with + or -. 

Generally, gsize and gfont appear at the beginning of a document, 
but they can also appear within a document, and may be changed as 
often as needed. 

For example, in a footnote in which the size of an equation should 
match the size of the foomote text (footnote text is usually two points 
smaller than the main text), global size should be reset at the end of the 
foomote. 

9. Debugging eqn 
9.1 Error conditions 

You can detect missing delimiters and other equation errors with 
program aids. Using the troubleshooting devices described here should 
be considered the initial step in formatting a document. 

An internal buffer in the trof f formatter limits the size of in-line 
equations. If a word overflow message is received, the limit has 
been exceeded. One solution is to break the equation into smaller units 
with the in-line delimiters. Printing the equation in a display can also 
solve the problem. The line overflow message indicates that an 
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even larger buffer has been exceeded. In this case, the equation must 
be broken into two separate pieces, marking each with . EQ/ . en 

delimiters. f 

\ 

Note: eqn does not warn you about equations that are too long 
for one line. 

If a mistake is made in an equation, such as omitting a brace, having 
one too many braces, or having an operator with a missing argument, 
eqn produces the following message: 

syntax error between lines x and y, file z 

where x and y are approximately the lines between which the trouble 
occurred, and z is the name of the file in question. There are also self- 
explanatory messages that arise when you have omitted a quote or you 
run eqn on a nonexistent file. To check a document before printing, 
use the command 



eqn files > /dev/null 

This discards the output but prints the appropriate messages on your 
terminal screen. 

9.2 The checkeq program 

The checkeq program checks for misplaced or missing delimiters. 
You run it with the following command: 

checkeq file 

Output from checkeq is written to the standard output, or can be 
redirected to a file as follows: 

checkeq file > output file 
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Table 7-1. Standard mathematical characters 



Input 


Output 


> = 


> 


< = 


< 


= = 


= 


! = 


?£ 


+ - 


± 


- > 


-> 


< - 


<- 


< < 


« 


> > 


» 


inf 


oo 


partial 
half 


a 


prime 


/ 


approx 

nothing 

cdot 




times 


X 


del 


A 


grad 
dollar 


V 

$ 


t ' • ' 1 

sum 


'z' 


int 




prod 


n 


union 
inter 


u 
n 
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Table 7-2. Greek alphabet 



Input 


Output 


Input 


Output 


alpha 


a 


ALPHA 


ALPHA 


beta 


P 


BETA 


BETA 


gamma 


Y 


GAMMA 


r 


delta 


6 


DELTA 


A 


epsilon 


8 


EPSILON 


E 


zeta 


c 


ZETA 


ZETA 


eta 


Tl 


ETA 


ETA 


theta 


e 


THETA 





iota 


I 


IOTA 


IOTA 


kappa 


K 


KAPPA 


KAPPA 


lambda 


X 


LAMBDA 


A 


mu 


[i 


MU 


MU 


nu 


V 


NU 


NU 


xi 


4 


XI 


E 


omicron 





OMICRON 


OMICRON 


pi 


n 


PI 


n 


rho 


P 


RHO 


RHO 


sigma 


a 


SIGMA 


E 


tau 


X 


TAU 


TAU 


upsilon 


\) 


UPSILON 


Y 


phi 


^ 


PHI 


O 


chi 


X 


CHI 


CHI 


psi 


¥ 


PSI 


^ 


omega 


CO 


OMEGA 


a 



Note: As shown in Table 7-2, several uppercase Greek letters 
are not provided in the eqn package. These uppercase Greek 
letters may be produced using trof f codes. See the 
Reference tables in Chapter 3, "nrof f/trof f Reference." 
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Table 7-3. Additional character set 



Input 


Output 


Input 


Output. 


circle 


O 


3dot 


; 


ciplus 


e 


incl 


E 


citimes 


® 


langle 


< 


Squarter 


3/4 


rangle 


> 


quarter 


1/4 


member 


G 


<-> 


«-> 


nomem 


4 


<=> 


<^ 


oppA 


V 


=del 


A 


oppE 


3 


hbar 


n 


cup 


u 


Ppd 


1 


cap 


n 


prop 


oc 


subset 


cz 


ang 


A 


! subset 


c 


angstrom 


A 


supset 


z> 


square 


n 


! supset 


2 


blot 


■ 


bigstar 


5K 


bullet 


• 


star 


* 


empty 





degree 





thf 


. 


wig 


~ 


-wig 


» 


=wig 


= 


>wig 


> 


<wig 


< 
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1. pic: a picture drawing program 

pic is a language for including pictures and diagrams in documents 
produced with trof f . It is usually used to draw relatively simple 
pictures, but the language can be used to describe even very 
comphcated graphic objects. 

pic operates as a trof f preprocessor, in the same style as eqn and 
tbl. Pictures are marked in the text by enclosing their descriptions 
between .PS and . pe pairs. The pic preprocessor translates these 
descriptions into the language understood by t rof f . 

2. Using pic 

2.1 Command syntax 

pic is usually run with the command line 

pic file I troff -mm 



If equations and tables also are present, you should run pic before 
eqn and tbl: 

pic file I tbl I eqn | troff -mm 



2.2 troff Interface 

Within pic specifications ( . PS and . PE pairs), an input line that 
begins with a period is assumed to be a trof f command and is copied 
to the output for further processing. Point size and font changes can be 
made within a pic specification: 
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.PS 

.ps 24 

circle radius .4i at 0,0 

• ps 12 

circle radius .2i at 0,0 

.ps 8 

circle radius .li at 0,0 

.ps 6 

circle radius .05i at 0,0 

.ps 10 

.PE 

This produces the diagram 




But trying to add blank lines or changing the vertical spacing within a 
picture interferes with the way pic draws objects. 

Point sizes, fonts, and local motions can be manipulated within quoted 
strings ("...") provided that whatever changes are made are reversed 
before exiting from the string. For example, to print text in italic font, 
point size 12, use 

ellipse "\sl2\f2Hello!\fl\s0" 

This produces 

rHello!\ 
3. Defining tlie picture format 

A picture specification begins with a picture start command (.PS) and 
concludes with a picture end command ( . PE). The . P S and . PE are 
used by t rof f as command delimiters. The general format of pic 
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input IS 

.PS optional-width 
picture-specifications 

.PE 

If optional-width is present, the picture is made that many inches wide, 
regardless of any dimensions used internally. The height is scaled in 
the same proportion. 

If the .PS line is written 

.PS < file 

the contents of file are inserted in place of the picture start command 
(whether or not the file contains . P S or . PE). 

pic copies the . PS and . PE lines from input to output intact, except 
that it adds two arguments to the .PS: 

.PS hw 

where h and w are the picture height and width in units. 

The definitions of the .PS and . PE macros do not automatically center 
pictures. However, if you include the following trof f instructions at 
the beginning of your document, your picture will be centered and 
offset from surrounding text. 



.de PS 
.if t . sp 
.in (\\n(. 
.ne \\$lu 


.3 
,lu-\\$2u) /2u 


.de PE 




. in 

.if t .sp 


.6 



If . PF is used instead of the picture end command ( . PE), the position 
after printing the picture is restored to what it was before the picture 
started (F is for "flyback"). Text can be overprinted on pictures, or 
several pictures can be superimposed. 
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Specifications must be separated by newlines or semicolons; a long 
element may be continued by ending the line with a backslash ( \ ). 
Comments are introduced by a # and terminated by a newline. 

If an error is made in the picture specification, pic generates an error 
message. For example, the invalid input 

box arrow box 

will print the message 

pic: syntax error near line 5;. file - 
context is 

box arrow " box 

The caret (") marks the place where the error is encountered; it 
typically follows the word in error. 

4. Specifying pictures: basics 

4.1 Primitive objects and their defaults 

The primitive objects provided by pic: boxes, lines, arrows, circles, 
ellipses, arcs, splines (arbitrary smooth curves), and text are shown 
graphically in their default sizes (see page 8-6 for splines): 



box 



line arrow 

>• 



( circle ] f ellipse 

arc 



C7 




A move (see "Object Attributes") also is considered an object; it goes 
from one point to another without drawing anything, so it is an 
invisible object. The following keywords specify primitive objects: 

box circle ellipse 
arc line spline 
arrow move 
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The following specification draws a simple box: 

.PS 

box "BOX" 

.PE 

which produces 




Boxes and lines may be dotted or dashed: 



I 



This picture was produced by 

box dotted; line dotted; move; box dashed; \ 
line dashed 

If there is a number after dotted, the dots will be that far apart. You 
can also control the size of the dashes. If there is a length after the 
word dashed, the dashes will be that long, and the intervening spaces 
will be as close as possible to that size. So, for instance. 



comes from this specification: 

line right 3i dashed 

line right 3i dashed 0.25i 

Circles and arcs cannot be dotted or dashed. 

A spline is a smooth curve guided by a set of straight lines; it begins 
and ends at the same place relative to the straight lines and in between 
is tangent to the mid-point of each guiding line. The syntax for a spline 
is identical to a line drawn along a path (see "Grouping Objects"): 
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spline right li then down .5i left li\ 
then right li 



produces 




4. 1 .1 Object attributes 

Attributes describe the positioning, size, and orientation of the object. 
When set, they operate on a single occurrence of an object. The 
attributes associated with each primitive object are shown in the 
following table: 



Object 



Attribute 



box 



circle /ellipse 



arc 



line/arrow 



spline 



move 



height, width, at, dotted, 
dashed, invis, same, text 

radius, diameter, height, 
width, at, invis, same, text 

up, down, left, right, 
height, width, from, to, at, 
radius, invis, same, cw, <-, 
->, <->, text 

up, down, left, right, 
height, width, from, to, by, 
then, dotted, dashed, invis, 
same, <-, ->, <->, text 

up, down, left, right, 
height, width, from, to, by, 
then, invis, same, <-, ->, 
<->, text 

up, down, left, right, to, 
by, same, text 



The keyword at places the geometrical center of an object in a 
specified place. 
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An object can be made invisible with the keyword invisible (or 
invis). This is particularly useful for positioning objects correctly 
near text. 

For lines, splines and arcs, height and width refer to arrowhead 
size. The width of an arrowhead is the distance across its tail; the 
height is the distance along the shaft. The arrowheads in this picture 
are default size: 




This was produced with the following code: 
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.PS 

box invis height 3i wid 4i 

A: circle at 0,1 "\f7/\fl" ^ 

B: circle at -1.5,0 "\f7bin\fl" ^ 

C: circle at -0.5,0 "\f7etc\fl" 
D: circle at 0.5,0 "\f 7tmp\f 1" 
E: circle at 1.5,0 "\f7usr\fl" 
F: circle at -1,-1 "\f7fl\fl" 
G: circle at 0,-1 "\f7f2\fl" 
arrow from A.s to B.n 
arrow from A.s to C.n 
arrow from A.s to D.n 
arrow from A.s to E.n 
arrow from C.s to F.n 
arrow from C.s to G.n 
.PE 

See "Blocks" for an explanation of the letters capitalized in this code. 

Dimensions are divided by scale during output, pic works 

internally in what it thinks are inches. Setting the variable scale to ( 

some value causes all dimensions to be scaled down by that value; for 

example, 

scale =2.54 

causes dimensions to be interpreted as centimeters. 

4.1.2 Object variables 

A variable consists of a keyword, which may or may not be followed 
by a value. Keywords are used to redefine object dimensions globally. 

Missing variables and values are filled in from defaults. Not all 
variables apply to all primitives; those which don't are ignored. 

The variables and their defaults are shown in the following table: 
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Object 


Variable 


Default 


Description 


box 


boxwid 
boxht 


0.75 in. 
0.50 in. 


box width 
box height 


circle 


circlerad 


0.25 in. 


circle radius 


ellipse 


ellipsewid 
ellipseht 


0.75 in. 
0.50 in. 


ellipse width 
ellipse height 


line or 
arrow 


linewid 
lineht 


0.50 in. 
0.50 in. 


line or an-ow width 
line or arrow height 


arc 


arcrad 


0.25 in. 


arc radius 


arrowhead 


arrowht 

arrowwid 

arrowhead 


0.10 in. 
0.05 in. 

2 


arrowhead height 
arrowhead width 
arrowhead style (filled) 


dash 


dashwid 


0.10 in. 


width of dashes or dots 


move 


movewid 
moveht 


0.50 in. 
0.50 in. 


width of horizontal move 
height of vertical move 



These may be changed at any time, and the new values will remain in 
force until changed again (see "Object Sizes: Changing the 
Defaults"). 

5. Object sizes: changing the defaults 

Figures are normally drawn at a fixed scale with objects of a standard 
size. It is possible, however, to expand a figure to fit a particular width. 
If the .PS line contains a number the drawing is forced to be that many 
inches wide, with the height scaled proportionately. For example, 

.PS 3.5i 

causes the picture to be 3.5 inches wide. 

The number given as a width in the .PS line overrides the dimensions 
given in the picture; this can be used to force a picture to a particular 
size even when coordinates have been given in inches. Experience 
indicates that the easiest way to get a picture of the right size is to enter 
its dimensions in inches, then if necessary add a width to the .PS line. 
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You can make any object any size you want. For example, using 
object attributes for width and height, the input 

box width 3i height O.li 

draws a long, flat box 3 inches wide and 1/10 inch high: 



Note: This specification changes the width and height of only 
that particular occurrence of the object. 

All positions and dimensions are assumed to be in inches; specifying 
the * ' i" is optional. However, if the " i" is present, there should be 
no spaces between it and the number it follows. 

The default size of an object can be changed by assigning values to the 
object variables. So if you want all your boxes to be long and skinny, 
and relatively close together, enter 

boxwid = O.li; boxht = li 

movewid = 0.2i 

box; move; box; move; box 

This produces 



In all cases, unless an explicit dimension for some object is specified, 
you will get the default size. If you want an object to have the same 
size as the previous one of that kind, use the keyword same. In the set 
of boxes produced by this specification: 

down; box ht 0.2i wid 1.5i; move down 0.15i; 
box same; move same; box same 
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the dimensions set by the first box are used several times; similarly, 
the amount of motion for the second move is the same as for the first 
one. 

6. Adding text to your picture 

Text is normally an attribute of some primitive; by default it is placed 
at the geometric center of an object. Each line of text is entered as a 
separate quoted string. Quotes are mandatory, even if the text contains 
no blanks. Each line is printed in the current point size and font, 
centered horizontally, and separated vertically by the current trof f 
line spacing value. 

If there are multiple text items for some primitive, they are centered 
vertically except as qualified. Positioning requests apply to each item 
independently; for example, 

.PS 

box "this is" "a box" 

.PE 

creates a standard box and centers the two pieces of text in it: 




Text items can contain t rof f commands for size and font changes, 
local motions, and so on, but make sure that these are balanced so that 
the entering state is restored before exiting from the string. 

A text item is a quoted string optionally followed by a positioning 
request: 
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"text" center 
"text" Ijust 
"text" rjust 
"text" above 
"text" below 

The attribute Ijust positions the left end at the specified point, and 
rjust positions the right end at that position, above and below 
center the text one half-line space in the given direction. 

Text is most often an attribute of some other object, but self-standing 
text can also be specified: 

"this Is some text" at 1,2 Ijust 

Text is centered on lines and arrows; if there is more than one line of 
text, the lines are centered above and below: 



above , ^ 
5»- on top of 



below 



above ^ - 

->- on top e f 



below 



above 
)n top e 
below 



These were produced with the following specifications: 

.PS 

arrow "below" below; move 

arrow "above" above; move 

arrow "on top of"; move 

arrow "above" "below"; move 

arrow "above" "on top of" "below" 

.PE 

7. Object positioning 

A position is ultimately an x,y coordinate pair, and you may specify a 
position in this way. But a position can be specified in other ways: you 
may position an object in relation to a part of some other object with 
the move and move to commands, or by using a label embedded in a 
grouped object. These are discussed in "Using Coordinates." 
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7.1 Using coordinates 

pic uses a standard Cartesian coordinate system, so any point or 
object has an X and y position. The first object is placed with its start at 
position 0,0 by default. The x,y position of a box, circle, or ellipse is its 
geometrical center; the position of a line or motion is its beginning; the 
position of an arc is the center of the corresponding circle. 

Position modifiers such as from, to, by, and at are followed by an 
x,y pair, and can be attached to boxes, circles, lines, motions, and so 
forth, to specify or modify a position; for example. 




is produced by the input 

• PS 

box dotted 

line dashed to 2,0 

.PE 

You can also use up, down, right, and left with line and move: 

• PS 2 

box ht 0.2 wid 0.2 at 0,0 "1" 

move to 0.5,0 

box "2" same 

move same 

box "3" same 

.PE 

to draw three boxes, like this: 



1 




2 




3 



Note the use of same to repeat the previous dimensions instead of 
reverting to the default values. 

Attributes such as ht and wid and positions like at can be written in 
any order: 
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box ht 0.2 wid 0.2 at 0^0 
box at 0,0 wid 0.2 ht 0.2 
box ht 0.2 at 0,0 wid 0.2 ( 

These are equivalent, although the last is harder to read and therefore 
less desirable. 

The from and to attributes are particularly useful with arcs, to specify 
the endpoints. For example, these arcs: 




were produced with the following specifications (respectively): 

arc from 0.5i,0 to 0,0. 5i 
arc from 0,0. 5i to 0.5i,0 

If the from attribute is omitted, the arc starts at the current position 
and goes to the point indicated by to. The radius can be made large to 
provide flat arcs: 

arc -> cw from 0,0 to 2i,0 rad 15i 

This produces 



Notice that to put an arrowhead on an arc, you can use <-, ->, or <-> 
as an attribute. 

7.2 Using comers 

To cut down the need for explicit coordinates, most objects have 
"comers" named by compass points: 
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B.nw 



B.w 



B.sw 



B.ne 




B.se 



The primary compass points may also be written as .r, .b, .1, and 
. t, for right, bottom, left, and top. The box above was 
produced with these specifications: 

.PS 1.5 

B: box "B.c" 

" B.e" at B.e Ijust 

" B.ne" at B.ne Ijust 

" B.se" at B.se Ijust 

"B.s" at B.s below 

"B.n" at B.n above 

"B.sw " at B.sw rjust 

"B.w " at B.w rjust 

"B.nw " at B.nw rjust 

.PE 

Note the use of Ijust, rjust, above, and below to alter the 
default positioning of text, and of a blank with some strings to help 
space them away from a vertical line. 

Lines and arrows have a start, an end, and a center in addition to 
comers. (Arcs have only a center, a start, and an end.) There are many 
ways to indicate the comers of an object Besides the compass points, 
almost any sensible combination of left, right, top, bottom, 
upper, and lower will work. Furthermore, if you don't like the "." 
notation, as in: 

last box.ne 

you can instead say 

upper right of last box 

It is sometimes easiest to position objects by positioning some part of 
one at some part of another, for example the northwest comer of one at 
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the southeast comer of another. The with attribute in pic permits 
this kind of positioning; for example, 



box ht 0.75i wid 0.75i 
box ht 0.5i wid 0.5i with 



sw at last box.se 



produces 



Notice that the comer after with is written . sw. 
As another example, consider: 

ellipse; ellipse with .nw at last ellipse.se 
which produces 




7.3 Object labels 

Objects can be labeled or named for future reference; for example. 



.PS 
Boxl 



.PE 



box 

# ... other stuff .. . 

move to Boxl 



Place names have to begin with uppercase letters to distinguish them 
from variables which begin with lowercase letters. The name refers to 
the ' 'center' ' of the object, which is the geometric center for most 
objects. For lines and motions, it refers to the beginning point. 
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Other combinations also work: 

line from Boxl to Box2 
move to Boxl up 0.1 right 0.2 
move to Boxl + 0.2,0.1 
line to Boxl - 0.5,0 

The reserved name Here may be used to record the ciurent position of 
some object; for example, 

Boxl : Here 

Labels are variables; they can be reset several times in a single picture, 
so a line of the form 

Boxl: Boxl + li,li 

is perfectly legal. 

You can also refer to previously drawn objects of each type, using the 
word last. For example, given the input 

box "A"; circle "B"; box "C" 

last box refers to box C, last circle refers to circle B, and 
2nd last box refers to box A. Numbering of objects can also be 
done from the beginning, so boxes A and C are 1st box and 2nd 
box respectively. 

7.4 Positioning with move 

If you want to leave a space at some designated place, use move: 

box; move; box; move; box 
This produces 



7.5 Positioning with variables 

It's generally a bad idea to write everything in absolute coordinates if 
you are likely to change things, pic variables let you set parameters 
for your picture: 



pic Reference 



8-17 



a = 0.5; b = 1 

box wid a ht b 

ellipse wid a/2 ht 1.5*b 

move to Boxl - (a/2, b/2) 

Expressions use the standard operators +,-,*,/, and %; pic uses 
parentheses, ( ) , for grouping. 

Probably the most important variables are those that are predefined for 
controlling the default sizes of objects. These may be set at any time in 
any picture, and retain their values until reset. 

You can use the height, width, radius, and x and y coordinates of any 
object or comer in an expression: 

Boxl .X the jc coordinate of Boxl 

Boxl . ne . y the y coordinate of the 

northeast comer of Boxl 

Boxl . wid the width of Boxl 

Boxl . ht the height of Boxl 

2nd last circle, rad the radius of the 2nd last 

circle 

Any pair of expressions enclosed in parentheses defines a position; 
furthermore such positions can be added or subtracted to yield new 
positions. If ( p i , />2 ) are positions, then ( /? i.x , p2.y ) refers to the 
point. 

8. Grouping objects 

Objects are connected in the direction specified by the most recent up, 
down, left, or right (either alone or as part of some object), with 
the entry point of the second object attached to the exit point of the 
first; for example, 

arrow left ; box; arrow; circle; arrow 

produces 
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left indicates connection toward the left. This could also be written 
as: 

left; arrow; box; arrow; circle; arrow 

Entry and exit points for boxes, circles, and ellipses are on opposite 
sides and at the start and end of lines, motions, and arcs. 

By default, arcs are drawn 90 degrees counterclockwise from the 
current position. To change the direction to clockwise, use this 
command: 

arc cw 

For example, this specification: 

line; arc; arc cw; arrow 
produces 



Lines and arrows are easily drawn by specifying amount of motion and 
direction. Accordingly, the words up, down, left, and right and 
an optional distance can be attached to line, arrow, and move. For 
example, 

.PS 

line up li right 2i 

arrow left 2i 

move left . li 

line <-> down li "height" 

.PE 

draws 
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height 



The notation <-> indicates a two-headed arrow; use -> for a head on 
the end and <- for one on the start. Lines and arrows are really the 
same thing; in fact, arrow is a synonym for "line ->' ' . 

If you don't put any distance after up, down, and so on, pic uses the 
standard distance: 

line up right 
line down 
line down left 
line up 

draws a parallelogram 




If a set of commands is enclosed in braces {...}, the current position 
and direction of motion when the group is finished will be exactly 
where they were when entered. Nothing else is restored. 

Note: There is also a more general way to group objects, using 
brackets (see "Blocks"). 

Although objects are normally connected left to right, this can be 
changed. If you specify a direction as a separate object, subsequent 
objects will be joined in that direction. Thus: 
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down; ellipse; arrow; circle 
produces 




and 



left; box; arrow; ellipse; arrow; circle 



produces 




A line may actually be a path; that is, it may consist of segments 
connected in a direction like this: 



This line was produced by 

line right li then down 
then right li 



5i left li\ 



The elements of a path, whether for line or spline, are specified as a 
series of points, either in absolute terms or by up, down, and so forth. 
If necessary to disambiguate, the word then can be used to separate 
components, as in 
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line right then up then left then up 
This produces 



and is not the same as 

line right up left up 
which produces 



8.1 Blocks 

Any sequence of pic statements may be enclosed in brackets [ . . .] to 
form a block, which is then treated as a single object and manipulated 
like an ordinary box. For example, the code 



box "1" 
[ box "2", 



arrow "3" above; box "4" ] \ 



with .n at last box.s - (0,0.1) 
"thing" at last [] .s 

produces the following picture: 
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thing 



Notice that last-type constructs treat blocks as a unit and don't look 
inside for objects: last box . s refers to box 1, not box 2 or 4. You 
can use last [ ] , and so on, just like last box. 

Blocks have the same compass comers as boxes (determined by the 
bounding box). You can position a block by placing either an absolute 
coordinate (like , 0) or an internal label (like A) at some external 
point, as in 

[...; A: ...;.,. ] with .A at . . . 

Blocks join with other objects at the center of the appropriate side. 

Names of variables and places within a block are local to that block, 
and thus do not affect variables and places of the same name outside. 
You can get at the internal place names with constructs like this: 



last [] .A 



or: 



B.A 



where B is a name attached to a block like so: 



[ 



] 



When combined with define statements (see "Macros"), blocks 
provide a reasonable simulation of a procedure mechanism. 

Even though blocks may occur inside of other blocks, you can look 
only one level deep with qualifiers such as B . A. The block A may be 
further quaUfied so that specifications such as B . A , sw refer to the 
southwest comer of the block named A which is inside block B. 

For example, the object 
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is produced with these specifications: 



Ih 


= .5i 




dh 


= .021 




dw 


= .11 




[ 






Ptr: [ 




boxht = h; 


boxwld 


A: 


box 




B: 


box 




C: 


box 




box wid 2* 


boxwld " 


D: 


box 





Block: [ 

boxht = 2*dw/ boxwld = 2*dw 

movewld = 2*dh 

A: box; move 

B: box; move 

C: box; move 

box Invls "..." wld 2*boxwld; move 

D: box 

with .t at Ptr.s - (0,h/2) 

arrow from Ptr. A to Block. A. nw 

arrow from Ptr.B to Block. B.nw 

arrow from Ptr.C to Block. C.nw 

arrow from Ptr.D to Block. D.nw 

] 

box dashed ht last [] .ht+dw wld last\ 

[] .wld+dw at last [] 
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8.2 The chop facility 

Sometimes it is desirable to have a line intersect a circle at a point that 
is not one of the eight compass points pic knows about. In such cases, 
the proper visual effect can be obtained by using the attribute chop to 
chop off part of the line: 

circle "a" 

circle "b" at 1st circle - (0.75i, li) 

circle "c" at 1st circle + (0-75i, -li) 

line from 1st circle to 2nd circle chop 

line from 1st circle to 3rd circle chop 

This produces 




By default, the line is chopped by circlerad at each end. This can 
be changed with the command: 

line ... chop r 
which chops both ends by r, and this specification: 

line ... chop rl chop r2 

chops the beginning by rl and the end by r2. 

Another form of positioning refers to a point as a fraction of the way 
between two other points: 

fraction of the way between positionl and position! 

fraction is any expression, stnd positionl and position! are any 
positions. You can abbreviate this: 
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fraction < positionU position2 > 

For example, 

box 

arrow right from 1/3 of the way\ 
between last box.ne and last box.se 
arrow right from 2/3 <last box.ne, \ 
last box.se> 

produces 



5»- 



The distance given hy fraction can be greater than 1 or less than 0. 

9. Macros 

pic provides a rudimentary macro facility, the simple form of which is 
identical to that in eqn: 

define name X replacement-text X 

This defines name to be the replacement-text', X is any character that 
does not appear in the replacement. Any subsequent occurrence of 
name will be replaced by replacement-text. Macros with arguments are 
also available. The replacement text of a macro definition may contain 
occurrences of $ 1 through $ 9; these will be replaced by the 
corresponding actual arguments when the macro is invoked. The 
invocation for a macro with arguments is 

name (,argl , arg2 , ...) 
Nonexistent arguments are replaced by null strings. 
As an example, one might define a square: 

define square X box ht $1 wid $1 $2 X 
Then 

square (li, "one" "inch") 
calls for a 1 inch square with the obvious label, and 
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square (0 .5i) 
calls for a square with no label: 



1 

inch 









Coordinates like x,y may be enclosed in parentheses, as in {x,y) ,so 
they can be included in a macro argument. 

10. Mathematical functions 

pic provides a number of built-in arithmetic, trigonometric, and 
random number functions. These are listed in the following table: 



Function 



Description 



log{e) 
sqrt (e) 
int (e) 
sin (e) 
cos (e) 

atan2 (61,62) 
max (61,^2) 

min(ei,e2) 
rand (6) 



natural logarithm of expression e 
square root of e 
integral part of e 
sine of e 
cosine of e 

arctangent of 61/^2 
maximum of e 1 and 62 
minimum of 6 1 and 62 
random number from 1 to e 



The arguments to the trigonometric functions (sin, cos, atan2) are 
assumed to be in radians. All other dimensions are assumed to be in 
inches. Examples using these functions can be found in the next 
section. 

11. Loops and conditional statements 

Newer versions of pic provide two very useful features: for loops 
and conditionals with if. An example of the for loop is as follows: 
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.PS 

for len=0 to 2 by 0.1 do 
X 

line right len ; line up len 
move left len ; move down len 
move down . 1 
X 
.PE 

This will produce 



±\ 



The character X can be replaced by any other unique character; it 
serves merely to delimit the statements that pic will loop through. 
Also, the increment specifier by . 1 may be omitted; if so, the 
increment specifier defaults to 1. 

You may execute pic commands conditionally by using the if 
construction. The following example draws 15 boxes at random 
locations; in addition, all boxes whose length exceeds the height are 
dashed, while the rest are dotted: 
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id 






.i1p±l 



_ J:_-_-_-_-_-I- ■ 






I I 



1 

I 
I 



^:.jii.ir;^^5—— J— --=-==' rj; 



_ J — I 
I 



This was specified as 

.PS 

for num = 1 to 15 do 
W 

X = rand(50) /25 
y = rand(50) /25 
if ( X > y ) then 
Y 

box dashed wid x ht y at x^y 
Y else Z 

box dotted wid x ht y at x,y 
Z 
W 
.PE 

12. Expressions 

Expressions in pic are evaluated in floating point. All numbers 
representing dimensions are taken to be in inches. 
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expression : 



(modulus) 



- e 

( e ) 

variable 
number 
place . X 
place . y 
place . ht 
place . wid 

13. Examples 

The figures in this section contain examples of complicated pic 
specifications. 

Figure 8-1. Space Pig 
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Figure 8-2. Source code for "Space Pig" 

• PS 

.ps 100 

A: circle radius 1 at 0,0 

B: ellipse Wid (0.75) height (0.50) \ 

with .n at (0,0.1) 
C: circle radius (.075) \ 

with .e at B.c - (0.05,0) 
D: circle radius (.075) \ 

with .w at B.c + (0.05,0) 
line from (-.97,0.25) to (-.75,1.4) 
line from (0.97,0.25) to (0.75,1.4) 
line from (-.75,1.4) to (-.25,0.97) 
line from (0.75,1.4) to (0.25,0.97) 
define gogglesX 

@ [ up arc cw rad $1; line right $2;\ 

arc cw rad $1; \ 

arc cw rad $1; \ 

line left $2 ; \ 

arc cw rad $1 ] @ 
.ps 80 

E: goggles (0.33, 0.93) with .s at B.n 
.ps 40 

F: goggles (0.26, 0.90) with .c at E.c 
.ps 40 

move to (-0.25,-0.675) 
line right . 5 
.ps 10 
.PE 
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Figure 8-3. Sine and cosine curves 
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Figure 8-4. Source code for "Sine and cosine curves" 

.PS 
.ps -2 

pi = atan2 (0,-1) 

for i = to pi by 0.01 do 

X 

"." at i, sin(i) 

"." at i, cos(i) 
X 

line from (0,-1) to (0,1) 
line from (0,0) to (pi,0) 

for i = to pi by 0.05 do 
Y 

line from (i,0) to (i,sin(i)) - (0,.03) 
Y 

-ps +2 
• PE 
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Figure 8-5. File system diagram 



hashtab: 





nl 


dl 


n3 


d3 


... 


n2 


d2 
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Figure 8-6. Source code for "File system diagram" 

.PS 

boxht = .21/ boxwid = .31 

down; box; box; box; box ht 3*boxht "." "." "." 
L: box; box; box 'Invls wld 2*boxwid "hashtab:"\ 

with .e at 1st box .w 
right 
Start: box wld .5l\ 

with .sw at 1st box.ne + (.41, .21) "..." 
Nl: box wld .21 "nl"; Dl : box wld .31 "dl" 
N3: box wld .41 "n3"; D3 : box wld .31 "d3" 
box wld .41 " . . . " 
N2: box wld .51 "n2"; D2 : box wld .21 "d2" 

arrow right from 2nd box 

ndblock 

spline -> right .21 from 3rd last box\ 

then to Nl.sw + (0.051,0) 
spline -> right .31 from 2nd last box\ 

then to Dl.sw + (0.051,0) 
arrow right from last box 
ndblock 
spline -> right .21\ 

from 3rd last box\ 

to N2 .sw-(0.051, .21) \ 

to N2.sw+(0 .051,0) 
spline -> right .31 from 2nd last box\ 

to D2.SW- (0 .051, .21) \ 

to D2.sw+(0 .051,0) 
arrow right 2*llnewld from L 
ndblock 
spline -> right .21 from 3rd last box\ 

to N3.SW + (0.051, 0) 
spline -> right .31 from 2nd last box\ 

to D3.SW + (0.051,0) 
.PE 
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Figure 8-7. Geometric shape 




Figure 8-8. Source code for "geometric siiape" 

• PS 

pi = 3.14159; n = 20; r = 1 
s = 2*pi/n 
for i = 1 to n-1 do 
X 
for j = 1+1 to n do 
Y 
line from r*cos(s*i), r*sin(s*i)\ 
to r*cos(s*j), r*sin{s*j) 

y 

X 

.PE 
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1. grap: a graph drawing program 

grap is a language for describing graphs and charts that are included 
in documents produced with trof f . Figures 9-1 and 9-2 are simple 
examples of the kind of output that you are able to produce using 
grap. 

Figure 9-1. A simple graph 
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Program size (bytes) 

Figure 9-1 is a typical bar chart, depicting the relative sizes of some of 
the AAJX text processing tools. Figure 9-2, on the other hand, is quite 
a different kind of graph; it gives us a graph of the sine curve over one 
cycle. 
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Figure 9-2. A more complicated graph 




grap operates as a pic preprocessor, in the same way that pic 
operates as a t rof f preprocessor. Graphs are marked in the text by 
enclosing their descriptions between . Gl and . G2 pairs. The grap 
preprocessor translates these descriptions into the language understood 
by pic, which must then be called to translate the grap output into 
pure t rof f commands. 

This chapter is designed to acquaint you with grap. The grap 
keywords and commands are introduced largely through examples. A 
complete reference list of grap syntax is given in the last section of 
this chapter. 

2. Using grap 

grap is usually run with the command line 

grap file \ pic I trof f -mm 

If equations and tables are also present, you should run grap and pic 
before eqn and tbl. 

grap file \ pic I tbl I eqn | trof f -mm 

There are two command-line arguments understood by grap: 

-Htype Set the output device to type. Currently supported devices 
are aps for the Autologic APS-5, and dilO for the 
Imagen Imprint 10. The default device is aps. In general, 
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however, this argument can be omitted with no ill effects. 

-1 Do not include the file containing macro definitions, 

/usr/lib/dwb/grap. defines. By default, this file 
is included whenever grap is called. 

3. Defining the graph format 

A graph specification begins with a graph start command ( . Gl) and 
concludes with a graph end command ( . G2). The . Gl and . G2 are 
used by trof f as command delimiters. The general format of grap 
input is 

.Gl 
chart-specifications 

.G2 



Individual commands must be separated by newlines or semicolons; a 
long element may be continued by ending the line with a backslash (\). 
Comments are introduced by a # and terminated by a newUne. 

In addition to grap commands, the chart specification can also include 
trof f and pic commands, trof f dot commands may be included 
if they begin a new line; such commands are most useful for changing 
point sizes in order to get thicker or thinner lines. Included pic 
commands must be preceded by the keyword pic; this instructs grap 
to ignore the rest of the line, passing it on to pic. 

4. Specifying charts: default actions 

The following table lists real and projected UNIX operating system- 
based hardware shipments for the years 1984 to 1990; as the table 
heading indicates, dollar amounts are in billions of U.S. dollars and 
units shipped are in thousands. 



grap Reference 9-3 



The UNIX market 


Year 


Revenues 


Units shipped 




(billions) 


(thousands) 


1984 


5.3 


127.1 


1985 


6.5 


161.3 


1986 


7.9 


205.0 


1987 


9.5 


265.0 


1988 


11.3 


340.0 


1989 


13.9 


414.0 


1990 


16.8 


485.0 



The same data can be entered as a list of numbers using the simplest 
grap specifications. For instance, the following input 



.Gl 










1984 


5 


3 


127 


1 


1985 


6 


5 


161 


3 


1986 


7 


9 


205 





1987 


9 


5 


265 





1988 


11 


.3 


340 





1989 


13 


.9 


414 





1990 


16 


.8 


485 





.G2 











produces the graph in Figure 9-3. 

This chart illustrates many of grap's default actions. First of all, 
unless instructed otherwise, grap will plot the data in a frame that is 
three inches wide and two inches tall. Also, grap automatically 
supplies ticks indicating the ranges of the data points, drawing them 
along the left and bottom sides. The ticks are arranged to leave a 
margin of 7 percent on all sides of the graph. The default plotting tool 
is the bullet. Finally, grap interprets the data in both the second and 
third columns as belonging to the data in the first column, and (unless 
told differently) interprets them in the same scale. So grap has plotted 
the yearly system revenues in the same coordinate system as it used to 
plot the number of units shipped. 

Obviously, this chart could stand some improvement. One major 
failing is the lack of text labeUng the various axes and the data points. 
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Figure 9-3. The default graph 
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Also, the bullets look rather lonely plotting the data points. It would be 
nice to do better, and grap provides numerous facilities to override 
and supplement its default actions. All in all, the following chart 
represents the original information much better: 
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Figure 9-4. A better graph 
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The following sections provide the information necessary to turn 

grap's default chart into this more elaborate chart. 

( 

5. Adjusting the frame 

Every graph is surrounded by a frame (which may be invisible); this 
determines the size of the graph. You can adjust the size of the frame 
with the grap command frame. For instance, the command 

frame ht 3 wid 4 

will set the height to three inches and the width to four inches. Because 
grap ultimately translates its input into pic commands, the largest 
graph is the largest possible pic drawing. 

By default, the frame is drawn solid; this can be changed by adding an 
attribute specifier to the frame command. For the moment, disregard 
the second column of data. So you might have 



5 wid 3 . 5 



frame 


dashed ht 2 


1984 


127.1 


1985 


161.3 


1986 


205.0 


1987 


265.0 


1988 


340.0 


1989 


414.0 


1990 


485.0 


.G2 
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Figure 9-5. A dotted frame 



500 -f 



In addition to dashed, other available drawing attributes are dotted, 
invis, and solid. 

You may also specify that only parts of the frame be drawn with a 
specific attribute. For example, the following is very common: 

frame ht 3 wid 4 top invis right invis 

This will draw only the bottom and left sides. 

6. Adding text to a chart 

grap contains several ways to put text of various sorts into a chart. 
You have already seen that grap automatically supplies ticks on the 
bottom and left sides indicating the ranges of the data points. More 
generally, text items can be placed in a chart with the plot command. 
For example, the command 

plot "A/UX introduced" rjust at 1987.5,300 

will print the indicated text at the indicated point, right justified. The 
default action is to center the text item at the specified point. Other 
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positional modifiers are 1 just, above, and below. Strings in grap 
are enclosed within double-quotes, as illustrated. Also, the word plot 
is optional. 

Labels can be added to any of the four sides of a chart using the 
label command. For example, 

label bottom "The 49ers'' Season" 

Multiple text strings are centered one above the others, as with pic. If 
the default placement of the labels is not acceptable, the labels may be 
shifted in any direction by adding a position modifier: 

label bottom "The 49ers' Season" down .1 

This will print the specified text, centered along the bottom of the chart, 
bumped down one tenth of an inch. Instead of down, the text can also 
be shifted up, left, or right. 

Text items can contain trof f commands for size and font changes, 
local motions, and so on, but you should make sure that these are 
balanced so that the entering state is restored before exiting from the 
string. So, for example, you might have the following: 

plot "\sl2The \fB49ers'\fP Season\sO" 

7. Grids 

It is sometimes useful to add grid lines to a chart, to indicate that a 
certain level has been achieved, to signal important events, or perhaps 
just to make the chart easier to read. Grid lines are specified with the 
command grid. For example. 
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.Gl 

frame ht 2.5 wid 3.5 top solid left solid 

grid bottom dotted at 1987.5 

plot "A/UX introduced" rjust at 1987.5,300 

1984 127.1 

161.3 

205.0 

265.0 

340.0 

414.0 

485.0 



1985 
1986 
1987 
1988 
1989 
1990 
.G2 



will produce the graph in Figure 9-6. 



Figure 9-6. Adding grid lines 



500 -f 



400- 



300- 



200- 




8. Using the shell 

There are three important ways in which grap can interact directly 
with the AAJX system. It can take input from files located in the AAJX 
filesystem, send output to the standard error file, and run arbitrary 
A/UX commands by passing instructions to the shell. 
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Instead of presenting your data to gr ap by including it in the chart 

specification, you can tell grap to get some data from a file. This is 

done with the copy command. For example, if the data is stored in a i 

file named unix . data, you could simply write the following: 

.Gl 

copy "unix. data" 

.G2 

The result of this graph specification is to produce the default chart 
given in Figure 9-3. Notice that you had to enclose the name of the file 
in double quotes. 

grap is also able to send information to the operating system. One 
way to do this is by using the print command. The print 
command sends its argument, either the value of an expression or a 
string, to the standard error output file. Usually this is the user's 
terminal screen. For instance, the command sequence 

• Gl 

X = 5 ,/ 

print x*7 "^ 

.G2 

will result in the value 35 being written on the user's screen. The 
print command is most useful for debugging purposes. 

By far the most powerful form of interaction between grap and the 
AAJX system is the sh command. The sh command passes its 
arguments (presumably commands) to the AAJX shell; these 
commands are executed, and control is then passed back to grap. 

A typical use of the sh command is to produce the data that will 
subsequently be plotted by grap using the copy command. For 
example, 

.Gl 

sh @ awk -f /tmp/awkscript chap.l > out @ 

copy "out" 

.G2 ( 

In this example, grap will run the awk program using the specified 
script and redirect the output into a file; this file, out, is then copied in 
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and grap continues processing the data it has just created. 
Presumably, the awk script generates columns of numbers that grap 
can understand. Note also that there is no reason that this grap input 
could not occur in the file chap . 1 itself. 

9. Macros 

grap provides a rudimentary macro facility, the simple form of which 
is identical to that in pic: 

define name X replacement-text X 

This defines name to be the replacement-text; x may be any character 
that does not appear in the replacement. Any subsequent occurrence of 
name will be replaced by replacement-text. 

Macros with arguments are also available. The replacement text of a 
macro definition may contain occurrences of the indicators $ 1 through 
$ 9; these will be replaced by the corresponding actual arguments when 
the macro is invoked. The invocation for a macro with arguments is 

name(argl, arg2, ...) 

Nonexistent arguments are replaced by null strings. 

10. copy thru 

grap contains a copy thru construction, identical to the one in 
pic, that allows the graph data to be interpreted according to the 
instructions defined earlier in a macro. A typical use of copy thru 
is 

.Gl 

define cprint @ circle rad $1 at $2, $3 @ 

copy "term. data" thru cprint 

.G2 

This will cause grap to open the file term . data in the current 
directory and plot a circle of radius determined by the first field at a 
location determined by the second and third fields. 

The data provided to copy thru does not need to be taken fi-om a 
file, nor does the macro need to be predefined. See the entry for copy 
in the section "Summary of grap Syntax" for a complete list of the 
possible forms that a copy thru construction can take. 
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11. Loops and conditionals 

Like pic, the grap program provides looping and conditional 
constiiictions. Looping through a sequence of statements can be 
achieved with the for command. The general form of a grap loop is 

for var = start to end [by step] do 
@ cmds @ 

If the optional step specification is omitted, the loop proceeds in 
increments of 1; also, the character ' @ ' may be replaced by any other 
character that does not occur in the series of commands cmds. In fact, 
the following form will also work, where the character '@ ' has been 
replaced by matching braces: 

for var = start to end [by step] do 
{ cmds } 

For instance, the curve corresponding to the equation 

y =x'^ 

can be obtained very easily using the following grap instructions. 

.Gl 

frame ht 3 wid 3 

draw solid 

for i = -2 to 2 by . 1 do 

{ 

next at i, i*i 

} 
.G2 

The resulting graph looks like this: 
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Figure 9-7. Plotting a simple curve 




The general form of the grap conditional statement is 

if cond then @ cmdsl @ [else @ cmds2 @] 

If the condition cond is true, then the sequence of commands cmdsl is 
executed. If the optional else clause is present and if the condition 
evaluates false, then the sequence of commands cmds2 is executed; 
otherwise it is ignored. 

You can add a simple if -statement to the previous example to shade in 
the positive side of the curve. 
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.Gl 

frame ht 3 wid 3 
draw solid 

for i = -2 to 2 by 0.1 do 
{ 

next at i, i*i 
if (i >= 0) then 

@ line from 0,i*i to i,i*i 
} 
.G2 

The resulting graph looks like this: 

Figure 9-8. Shading part of a curve 



4- 



2- 



0- 




12. Plotting curves 

You saw above in the section "Loops and Conditionals" that the grap 
language can be used to plot curves from equations as well as from 



9-14 



A/UX Text Processing Tools 



discrete data points. In general, you can use this method to graph any 
function y =f(x) where/ (x) can be expressed using the operators and 
functions built into grap. The built-in operators are 

+ addition 

subtraction 
* multiplication 
/ division 
= equality 

The built-in functions are 



exp iexpr) 

log iexpr) 

sin iexpr) 

cos iexpr) 

atan2 iexpr\,expr2) 

sqrt iexpr) 

int iexpr) 

ma X ( expr \ ,expr 2) 

mi n ( expr 1 ,expr 2) 

rand (expr) 



10 to the power expr 

logarithm base 10 of expression expr 

sine of expression expr 

cosine of expression expr 

arctangent of expr \l expr 2 

square root of expression expr 

integral part of expression expr 

maximum oiexpri and expr 2 

minimum of expr\ and expr 2 

a random number between 1 and expr 



Consider for example the built-in logarithm function log. This 
provides only the base- 10 logarithm, but you can define the natural 
(base e) logarithm if you recall the following simple fact: 

log^ {x) = log^ (10) X logio(x) 

Because log^ (10) is an easily-determinable constant, you can construct 
the following grap macro: 

define In @ 2.30258 * log($l) @ 

Furthermore, the function y = e* is the inverse function of >' = ln(jc), 
so you can graph it by reflecting the graph of the natural logarithm 
across the diagonal line y =x. So you have 
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.Gl 

define In @ 2.30258 * log($l) @ 

frame ht 4 wid 4 / 

draw Nat solid 

draw Ten dotted 

draw Exp solid 

for i = . 5 to 5 by . 1 do 
{ 

next Nat at i, ln(i) 

next Ten at i, log(i) 

next Exp at ln(i), i 
} 
line dashed from 0,0 to 4,4 
"$y-=~e sup X $" at 0.0, 2.00 
"$y~=~ln (X) $" at 2.0, 1.0 
"$y-=~log (x) •$" at 3.0, 0.65 
"$y~=-x $" at 4.5, 4.5 

.G2 

I 

This yields 
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Figure 9-9. Logarithmic and exponential functions 



4- 



2- 



0- 








12.1 Using polar coordinates 

Some curves are more easily described using polar coordinate 
equations than using Cartesian rectangular coordinates. For example, 
the polar equation of a circle with its center located at the origin is 
simply r = a , for some constant a , whereas the rectangular equation is 
the somewhat more complicated x'^ + y^= a^. Even though grap does 
not contain primitives for handling polar equations, it is relatively 
straightforward to graph some equations expressed in polar form, 
r=f(Q). 
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To see this, consider the following simple relationship between the 
sides of a right triangle: 



(x,y) 




rsin(0) 



rcos(0) 



You notice the following two facts: 

X =rcos(8) 
y =rcos(0) 

You can therefore graph the curve r =/ (0) by plotting the sets of point 
X ,y which satisfy the equations: 

x=/(0)xcos(0) 
}'=/(0)xcos(0) 

For example, suppose that you want to graph the Spiral of Archimedes, 
r = 0. The following grap input will do nicely: 

• Gl 

frame ht 3.5 wid 2 

label bot "Spiral of Archimedes" "$r~=~theta$" 

pi = 3.14159 

for i = to 3*pi/2 by 0.1 do 

{ 

next at i*cos(i), i*sin(i) 

} 
.G2 

This yields the graph: 
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Figure 9-10. Plotting a polar equation 



2- 




-4- 



I r 

3-2-1 

Spiral of Archimedes 
r=0 



Similarly, you can give the following code to generate the graph of the 
cardioid: 
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• Gl 

frame invis ht 3.0 wid 3 . 5 

grid bottom dotted at 

grid left dotted at 

ticks off 

label bottom "Cardioid" "$r~=~l~-~ cos ( theta ) $' 

"X" at 1,0.25 

"Y" at 0.25,1.5 

pi = 3.14159 

for i = to 2*pi by 0.07 do 

{ 

next at (1-cos (i) ) *cos (i) , (1-cos (i) ) *sin (i) 

} 
.G2 

This code yields 
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Figure 9-11. A second polar equation 




X 



Cardioid 
r = 1 - cos(e) 

As a final example of the power of this method, consider how easy it is 
to graph a circle using polar coordinates. You noted that the polar 
equation of a circle centered at the origin is just r =a. The necessary 
transformations into x,y pairs are therefore 

x=ax cos(G) 
y =a y. sin(0) 

So, for a circle of radius 1: 



grap Reference 



9-21 



.Gl 

frame invis ht 3 wid 3 

pi = 3.14159 

for i = to 2*pi by 0.05 do 

{ 

next at cos(i), sin(i) 

} 
next at 1,0 # close up graph 
.G2 



Figure 9-1 2. A grap circle 



0.5 



0- 



-0.5- 




-0.5 



0.5 



The interested reader should attempt to recreate this graph without 
using polar coordinates. (No fair using the pic built-in circle!) 



9-22 



A/UX Text Processing Tools 



12.2 Equally scaled axes 

You will notice that grap automatically calculates the bounds of the 
curve being graphed and scales the coordinate axes in such a way as to 
fit the graph into the space available (either the size requested using the 
frame command or the default size). This means that the axes are 
almost never drawn according to the same scale. For graphs of discrete 
data this is not generally a problem, but graphs of curves and functions 
are often misleading unless drawn with axes scaled identically. 

There is an easy way to get grap to produce equally scaled axes. The 
frame and coord state^nents can be used to specify that the size and 
coordinate ranges for both axes be identical. For instance, the 
following grap instructions will ensure that the curve looks the way 
you expect: 

.Gl 

frame ht 3 wid 3 

coord X 0,10 y 0,10 

draw solid 

for i from 0.1 to 10 by 0.05 do 

{ 

next at i, 1/i 

} 
.G2 

This yields 
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Figure 9-13. Equally scaled axes 



lO-T 




You will notice that obtaining equally scaled axes via the coord 
command demands that you have some previous idea of what the 
bounds of the function are likely to be. If you genuinely have no firm 
idea what the resulting graph is going to look like, you can still ensure 
equally-scaled axes in the following way: while plotting the set of 
points x,y over some interval, also plot the set of points y^ invisibly. 
This has the effect of plotting the inverse function y =f~^(x), thereby 
guaranteeing that the largest x value is the same as the largest}' value. 

To illustrate this second method of producing equal axes, suppose that 
you want to graph the curve y =x^. You can give the following code, 
which does not use the coord command: 
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• Gl 

frame ht 3 wid 3 

draw Real solid 

draw Hack, invis 

for i from to 3 by . 1 do 



{ 



next Real at i, i*i*i 
next Hack at i*i*i, i 



} 



.G2 



This will produce the following graph: 

Figure 9-14. Equally scaled axes without coord 



20- 



10- 




0- 



12.3 Plotting curves from data points 

Sometimes it is not possible to reduce an equation to the rectangular 
form y = / (x) or to the polar form r = / (9). In such a case, it is still 
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possible to obtain a graph of the function using grap, though not in the 
easy way illustrated earlier. 

Suppose you want to find a graph of the equation 

One way to do this is to write a simple program to generate a set of 
data points on the curve. Figure 9-15 illustrates a C language program 
that will generate a set of points on the curve between and 4. 

Figure 9-15. Sample C program to generate data points 

#include <stdio.h> 

#define STEP 0.01 /* step size between points */ 

#define MARG 0.01 /* margin of closeness */ 

#define approx(a,b) { (a>= (1.0-MARG) *b) && (a<= (1.0+MARG) *b) ) 

main () 
{ 

float X, y; 

for ( X = 0.0 ; X <= 4.0 ; X += STEP ) 
for ( y = 0.0 ; y <= 4.0 ; y += STEP ) 
if ( on_curve (x,y) ) 

printf ("%4.3f %4.3f\n", x, y) ; 
exit (0) ; 
} 

on_curve (fx, fy) 
float fx, fy; 
{ 

if ( approx { fx*fx*fx*fx*fx*fx*fx*fx , 
((fx*fx)+(fy*fy)) 
*((fx*fx)+(fy*fy)) 
*((fx*fx)+(fy*fy)) ) ) 
return (1) ; 
else 

return (0) ; 
} 

When this program is compiled and run, it will generate a list of data 
points. If the output of the command is redirected into the file 
curve . data, the following grap commands will give you the graph 
you want. 
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.Gl 

frame ht 3 wid 3 

coord X 0, 8 y -4, 4 

draw Pos solid 

draw Neg solid 

copy "curve. data" thru @ next Pos at $1,$2 

next Neg at $l,-$2 @ 
.G2 



This yields 



Figure 9-16. Plotting a curve from data points 
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13. Summary of grap syntax 

grap is a pic preprocessor designed for drawing charts and graphs 
and including them in documents formatted with trof f . The general 
command line is 

grap files \ pic | ... I troff ... 

Graph specifications are included between . Gl and . G2 pairs and may 
include the following commands: 

coord [dataset] x min,max y min,max [log x] [log y] 
Set the range of the x and y coordinate axes to run from 
min to max. This command overrides the default axis 
scaling and may result in the loss of data points that do not 
fit into the specified range. Addition of the optional log 
indicator will result in logarithmic scaling of the specified 
axis. The default dataset is the one currently active. 

copy "file" 

Include the hlcfile at this point. 

copy thru name 

Pass the rest of the input for this graph (that is, until the 
next . G2) through the macro nam£, breaking the line into 
fields that are passed as arguments to the macro. Fields are 
delimited by white space, except for white space enclosed 
by string delimiters, "...". The macro name can be 
replaced by an in-place macro. 

copy thru name until "str" 

As above, except that the copying ends when the first 
occurrence of the string str is found at the beginning of an 
input line. 

copy "file" thru name until "str" 

Copy the data from Glcfile through macro name until the 
first occurrence of the string str is encountered. 

define name X anything X 

Define a grap macro: replace all subsequent occurrences 
of name by anything. If the string anything contains any 
of the sequences $1,$2,..., $9, they are replaced by the 
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first, second, . . ., ninth arguments enclosed in parentheses 

following nam«. The file 

/usr/lib/dwb/grap, defines contains several 

macro definitions and it is included in all files processed by 

grap if it exists (unless the -1 command line option is 

specified). 

draw [dataset] attrib ["i'/r"] 

Set the attribute to be used in drawing the graph of data set 
dataset to attrib. If the optional string str is added, this 
string will appear at each point plotted. 

for var = start to end [by step\ do @ cmds @ 

Run the specified list of commands cmds for all the values 
between start and end, taken in steps of step. If the by 
clause is omitted, steps of 1 are taken. The assignment 
operator = can be replaced by the keyword from. 

frame [attrib] ht h wid w [side attrib] 

Set the frame surrounding the graph to the specified height 
h and width w. The default size is 2 inches high and 3 
inches wide. You may set the drawing mode attrib for the 
entire frame or for each of the sides (top, bot, left, 
and right) to any one of the attributes dotted, 
dashed, invis, or solid . The default attribute is 
solid. 

graph Name pos 

Begin a new frame Name for subsequent plotting, placing 
the frame at the specified pos. The position pos must be in 
a form recognizable by pic, for instance, 

graph New with .s at Old.n 

The name of the graph Name must be capitalized, in 
accordance with the input syntax for pic. 

grid side attrib at [dataset] expr 

Draw grid lines perpendicular to the specified side side at 
the value of expression expr. The line is drawn with 
attribute attrib, which is by default solid. There may be 
more than one expression, and grid fines and labels of 
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incremental steps are available as with the ticks 
command. 

if cond then @ cmdsl @ [else @ cmds2 @] i^ 

Run the commands cmdsl if the specified condition cond 
is true. If the condition evaluates false, and if the optional 
else clause is present, then run commands cmds2. 

label side "sir" ["str"] [pos expr] 

Use string str as a label on the specified side side. The 
default side is the bottom. There may be any number of 
strings, which are centered one above the others. In 
addition, a label specification may include an optional 
position pos to shift the default position of the label. The 
specifier po^" may be up, down, left, or right, and 
must be followed by an expression indicating the amount 
of position shift in the specified direction. 

line from pt to pt [attrib] 

Draw a line, using the specified attribute attrib, from the 

first point pt to the second. The default attribute is s o 1 id. C 

Also, the keyword line may be replaced by arrow. ^ 

new [dataset] attrib ["str"] 

Set the attribute to be used in drawing the graph of the data 
set dataset to attrib, and disconnect the subsequent data 
points from any preceding ones. If the optional string str is 
added, this string will appear at each point plotted. 

next [dataset] at pt [attrib] 

Plot the next data point for data set dataset at pointer, 
connecting that point with previous points by a line of 
attribute attrib. 

pic anything 

Pass the remainder of the input line to pic, removing any 
leading white space. The input anything cannot contain 
newlines. 

plot "str" [he] at pt ( 

Place string str at point /jr. The optional location loc can 
be any one of the modifiers r just, 1 just, above, or 
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below. Also, the keyword plot may be omitted 
altogether. 

point [datasei] expr,expr 

Map the point determined by the values of the two listed 
expressions to the specified dataset. The default data set is 
the current. 

print expr 

print "i'rr" 

Print the value of expression expr or the string str on the 
standard error file. This is most useful as a debugging tool. 

sh @ anything @ 

Pass everything between the enclosing @ 's to the AAJX 
shell. The character @ can be replaced by any other 
character. Also, newlines may be included in the string 
anything. 

ticks side dir at [datasei] expr ["str"] [, expr "str"] 
Draw ticks on the specified side side at expr, using the 
optional string str2&2L label. More than one expression 
and label can be listed, separated from the preceding ones 
by a comma. Direction dir may be either in or out, 
indicating the direction the ticks are drawn (the default 
direction is out). The strings specified as labels may 
contain format specifiers of the form % f n . /n, which are 
interpreted as with the C-language function print f. See 
print f (3) for details. 

ticks side dir from m to n [by step] ["str"] 

Draw ticks on the specified side side beginning at value m 
and continuing to value n in steps of size step, using the 
optional string s'fr as a label. The step size step may be 
preceded by an optional + or - to obtain additive 
increments or decrements, or by an optional * or / to 
obtain multiplicative increments or decrements. If the step 
specifier is omitted, steps of size 1 are used. If no ticks are 
requested, they will be supplied automatically, although 
thiscanbesuppressed with the command ticks off. A 
margin of 7% is left on each side of a graph; the margin 
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can be adjusted with the command 

margin = expr 

number-list 

Unless copied through a macro (see copy thru), treat a 
list of numbers as follows. A single column of numbers 
(one number per line) is interpreted as a list of ordinates 
(y- values) for the abscissae (x- values) 1, 2, 3, . . . Multi- 
columned lists are treated as a single abscissa followed by 
multiple ordinates; in other words, a line of the form: 

xyl y2 y3 ... 

will result in plotting the points (x,yl), (x,y2), (x,y3), and 
soon. 

var = expr 

Set variable var to the value of expression expr. 

. anything (at beginning of line) 

Copy this line untouched. Hence, trof f commands may 
be interspersed among grap commands. 

# anything 

The symbol # is a comment indicator; anything following 
this symbol on a line will be ignored by grap. You can 
also use the t rof f comment indicator . \ " at the 
beginning of a line to include comments in a graph 
specification. 
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1. Introduction 

The tools described here supplement the text processing programs 
described in this book. This chapter is intended as a short reference to 
these additional tools. For complete information on each command, 
refer to the AlUX Command Reference. 

2. Other text preprocessors 

Preprocessors operate with text formatters to produce specialized 
forms of output, such as tables, equations, and line drawings. 
Preprocessor data is converted to trof f (or nrof f ) commands, and 
then this output is passed on to the formatter for further processing. 

tbl, eqn, and pic are the most commonly used AAJX preprocessors. 
The following is a brief description of some lesser-known AAJX tools. 

2.1 Preparing constant-width text 

Text typeset in constant- width (CW) font resembles the output of 
terminals and line printers. All characters are the same width. CW 
font is used most often to show examples of computer output. 

CW font contains a nonstandard set of characters with character and 
interword spacing different from that of standard t rof f fonts, such as 
Times Roman. Documents using the CW font must be preprocessed. 

See cw(l) for more information. 

2.2 Numbering iines 

The nl program is a line-numbering filter. It reads Unes from a named 
file (or from standard input if no file is named) and reproduces the lines 
on the standard output. Lines are numbered on the left side of the page, 

nl processes your text in 'logical pages." Line numbering is reset at 
the start of each logical page. A logical page consists of a header, a 
body, and a footer section. Different line numbering options are 
available independently for each of these sections. For example, you 
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may specify that you do not want header or footer lines numbered. 
(The default is not to number either header or footer lines.) 

To specify the start of each logical page section, use the following ^ 

default delimiters, which appear at the line preceding the start of the 

section: 

\ : \ : \ : header 

\ : \ : body 

\ : footer 

Thus, for general purposes \ and : are considered to be the delimiter 
characters, as they are repeated and joined to form the actual 
delimiters. 

You may specify new delimiter characters by use of the -d flag option. 
For example, in the command 

nl -v5 -15 -d!+ test. file 

the delimiter characters are changed to ! +. The entire command ^ 

instructs nl to number test . file starting at line number 5 (-v5), \( 

with an increment of 5 (-15). (The default is to begin numbering at 
line 1 and to use an increment of 1.) 

For a complete description of the available options, see nl(l). 

2.3 Translating characters 

The t r program translates characters in a file. It takes two string 
arguments. Any characters found in the first string are replaced by the 
equivalent characters in the second string. 

For example, suppose you want to convert all uppercase characters in a 
file to lowercase. You can do this with the command 

tr "[A-Z]" "[a-z]" < upper. file > lower. file 

where " [A-z ] " is the first string, " [a-z ] " is the second string, 

upper . file is the original file, and lower . file is the translated 

file. The double quotes and brackets are necessary to distinguish / 

ranges from regular strings. If they are omitted, only the characters a, \ 

-, and z will be translated to lowercase. 
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You can also use tr to delete character strings. For example, if you 
want to remove all numeric characters from a file, you may use the 
command 

tr -d 0-9 < num. file > unnum.file 

With the -d option, you specify only one string and tr deletes 
members of it wherever they occur. Ranges do not need special 
treatment with this option. 

See tr(l) for more information. 

2.4 Single-spacing a document 

ssp removes extra blank lines from a file and causes all output to be 
single-spaced. You may use it either directly on a file: 

ssp file > out. file 
or as a filter following text formatting: 

troff -mm file | ssp > out. file 
See ssp(l) for more information. 

2.5 Changing the format of a text file 

The newf orm program allows you to change the format of a text file. 
You may change tab characters to spaces or spaces to tabs. You may 
define a standard line length, and if your input exceeds that length, you 
may designate that n characters be removed, from either the beginning 
or the end of each line. If your input lines are shorter than the 
designated line length, you may choose the number of characters to 
append or prefix to each line. For example, given test . file — a file 
with lines consisting of leading digits, one or more tabs, and then 
text — the command 

newf orm -s -i -e -a test. file > out. file 

converts it to a file (output . file) with lines beginning with text (- 
s), all t^bs expanded to spaces (-i), each line padded (or truncated) 
with spaces to fit 72-column format (-e), and the leading digits (which 
were stripped away with the -s option) appended after column 73 (- 
a). 

See newf orm(l) for more information. 
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2.6 Printing Greel< characters 

greek is an nrof f filter that permits you to produce an 
approximation of the greek alphabet on output devices not normally 
able to print nonstandard characters. 

The file / us r/ pub /greek contains the default Greek characters 
produced by nrof f . The greek filter reinterprets this character set 
(as well as the default reverse and half-line motions) to permit use on a 
variety of terminals. The special characters are simulated by 
overstriking. 

Your own terminal type may be specified after the -T flag option. 
Thus the command 

nroff -mm test, file I greek -Tterm 

(where term specifies the output device) formats test . file and 
filters the output through greek. (If no -T argument is given, greek 
attempts to use the environment variable $term.) 

greek recognizes only certain terminal types. To view the list of 
recognized terminal types, see greek(l). 

2.7 Creating underlines for your terminai 

The ul program translates underscore characters to a sequence that 
simulates underUning. The actual sequence depends on the options 
supported by your terminal. Some terminals produce reverse video to 
indicate underiining; others do actual underUning. If your terminal 
cannot interpret underscores, ul behaves like cat(l) and simply 
displays the file on your screen. 

You may specify the terminal type after a -t . This is the most reliable 
way to obtain underlining as such, if your terminal can do it. If no type 
is specified, ul wUl try to determine it from the environment and may 
consult /etc/termcap to learn how to underline. 

Thus the command 

nroff -mm test, file I ul -t term 

(where term is the terminal type) will format test. file and filter 
the result through ul to produce underlining wherever test . file 
had fines preceded by 
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.ul 
or had t rof f requests for italics. 
See ul(l) for more information, 

2.8 Stripping out reverse line feeds 

The col program allows you to print files that contain reverse line 
feeds and forward and reverse half-line feeds on output devices that 
cannot handle reverse movements. 

col filters out the reverse line feeds generated by the . rt (return) 
nrof f request, some eqn output, tbl output, and other multiple- 
column output. In addition to removing reverse line feeds, the col 
program filters out other nonprinting characters. You can then print 
your formatted file on simple printing devices. 

To run col on a multiple-column nrof f document, use the command 

nroff -itim test, file I col > output, file 

See CO 1(1) for a complete description of the use of this command. 

3. Other macro packages 

The mm and ms macro packages permit you to produce a wide range of 
text processed output. The following macros allow you to go a step 
further in document preparation. 

3.1 Typesetting viewgraphs and slides 

You may use the mv macros to prepare typeset-quality viewgraphs and 
slides. Viewgraphs can be prepared in a variety of dimensions, as well 
as 35-mm slides and 2-by-2-inch "super slides." A few macros 
perform most of the formatting tasks needed in making transparencies, 
and you may use all of the facilities of nroff, trof f , eqn, tbl, and 
cw for the more difficult tasks. See mv(5) for a complete list of the 
available macros. 

To run your text files prepared with mv, use the mvt command: 

mvt file > out. file 

Options are provided to call tbl and eqn and the proper pipelines and 
required arguments for trof f are generated automatically. 
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See mmt(l) and mvt(l) in AlUX Command Reference and mv(5) in 
AlUX Programmer' s Reference for more information. 

4. Special tools for the manual pages 

The AAJX manual pages found in the A/f/X" Command Reference , 
AlUX Programmer' s Reference, and AlUX System Administrator' s 
Reference contain descriptions of all commands and maintenance 
procedures contained in the AAJX system. The manual pages are 
produced according to strict formatting conventions with the man 
macros. 

4.1 Creating a manual page 

The man macros produce standardized manual entries. You use the 
man macro package to create manual pages in the same way that you 
use the mm macro package to produce text. 

To produce your own manual pages, follow the instructions in man(5). 

4.2 Reading on-line manual entries 

The man command locates and prints a requested manual entry. The 
manual page can be viewed on your terminal screen (the default) or can 
be printed on your printer. 

For example, to produce the manual page grep(l) for terminal 
viewing, enter the following- 
man 1 grep 

The 1 is the section number of the manual. It alerts the system to 
search through section 1. If the section number is not specified, the 
entire manual set (sections 1 through 8) is searched. 

See man(l) for more information. 

4.3 Creating a permuted index 

The permuted index in the AlUX Command Reference , AlUX System 
Administrator' s Reference , and AlUX Programmer' s Reference is 
produced with the ptx command. The permuted index presents a 
sorted alphabetic listing of keywords contained in the command 
descriptions. 

It works in three stages: 
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1. It generates one line for each keyword in an input line, and then 
rotates the keyword to the front of the line. 

2. It alphabetically sorts the permuted file. 

3. It rotates the sorted lines and places the keyword in the middle of 
the line. 

You can then scan the center column of the permuted index for the 
keywords. 

For flag options and formatting information, see ptx(l) and mptx(5). 

5. Checking your work before you format it 

The following tools check your work before you process it. With each 
command, output either can be written to standard output (the default) 
or redirected to a file. 

5.1 Checking your spelling 

The spell program checks the words in your document against an 
on-line dictionary and then reports those words not found. You can 
instruct spell to verify either American or British spelling. You can 
also stipulate a file (with the +local . file flag option) of words not 
in the on-line dictionary for spell to use as well. In this case, 
+local.file must be sorted, with one word per line. 

To run spell, type 

spell test. file > spell. list 

This checks the spelling of words in test. file and puts dubious 
ones in spell . list. 

Note: Proper names and technical terms appear in the spell 
output (unless you include them in your +local.file). 
Often, you will have to edit these out of your spell . list 
before using it to correct your files. 

For complete instructions on using the spell program, see spell(l). 

5.2 Checking your writing style 

You can check certain aspects of your writing style with the style 
program. It gives the use (by percentage) of various grammatical 
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forms, and it reports on readability, sentence length and structure, word 
length and usage, and types of verbs used. 

Although such statistics may seem superficial, they can still be of use, 
style is particularly useful for comparing two documents or seeing if 
you are overusing a particular grammatical form. 

To run style, enter the following: 

style file 

5.3 Checking your document's clarity 

The diction program finds sentences in a document that are 
overused or poorly constructed. It compares what is in your document 
against a data base of bad phrases and reports any matches. 

To run diction, enter the following: 

diction < file 

See diction(l) for additional information. 

5.4 Ciiecl<ing your eqn commands 

checkeq looks for missing or unbalanced eqn delimiters (usually 
$$)or .EQand .en pairs. It especially looks for mixtures of these, 
which would confuse eqn; thus the output 

$$ within .EQ .. .EN , line n 
indicates that in-line delimiters were used within a displayed equation. 
To run checkeq, type 

checkeq file 
Not all output lines flag errors directly. The diagnostic 

$$ delims, line n 

does not report an error. It states that in-line delimiters ($ $) were 
turned on at line n. If the delimiters change, this will also be reported. 
Then, if they are changed to another symbol or if they are left off for a 
long time, this will be apparent from the output. 

Note: Do not set delimiters to ## and then use eqn within 
tables, tbl uses #'s internally and may not be able to function 
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if eqn uses them as well. 

If you need to use the dollar sign itself, you can use the following eqn 
definition at the top of your file: 

.EQ 

define dol ' roman "$"' 

delim $$ 

.EN 

Because the single dollar sign appears in the file before the delimiters 
were turned on, this usage will not cause an error to be reported by 
checkeq. Then, to use this defined term, type 

$dol$ 

to produce $. The dollar signs match, and no error is flagged. 

Note: If you use the mm macros, you should use checkmm 
instead of checkeq. The checkmm program incorporates all 
the features of checkeq. 

5.5 Checking your mm commands 

checkmm checks for inconsistent use of the mm macros. It finds 
unmatched pairs of macros, unmatched size and font changes, and 
unbalanced . EQ . / . en pairs. If you use checkmm, you do not have 
to use checkeq as well. 

To run checkmm, enter the following: 

checkmm file 

For more information on options and syntax, see mm(l). 

5.6 Checking your ms commands 

You can check your ms documents for formatting errors with the 
checknr program, checknr examines your file and reports any 
unrecognized macros or unbalanced macro constructions. For 
example, it will find any . ds commands that are not terminated with 
. DE, or it will verify that each . RS command has a corresponding 
. RE command. 
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To run checknr, enter the following: 

checknr file 

Any discrepancies are written to the standard output. Or, if you prefer, 
you can direct the output from checknr to a jBle so you can examine 
it later: 

checknr file > output-file 

For more detailed instructions on using this program, refer to 
checknr(l) in AlUX Command Reference. 

5.7 Checking your cw commands 

You can use checkcw on files to be processed with cw. checkcw 
finds unbalanced left and right delimiters, as well as . cw/. CN pairs. 

See cw(l) in AlUX Command Reference for more information. 
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Document Formatting and Typesetting on the UNIX System 
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Additional Reading A-1 



Appendix B 
Glossary of Text Processing Terms 



adjust: To add small amounts of space between words in a filled text 
line so that the line of output text is the desired line length. 

argument: Used in a command line and placed after the command to 
specify what the command should act upon. 

break: Printing of a partially filled output line. 

comment: An informative remark embedded in text but not intended 
for printing. You can include a comment at the end of a line by 
prefacing it with \ . You can include a comment in a file as a fine by 
itself by beginning the line with . \ . 

control lines: Sometimes called "dot commands," they are 
interspersed with text lines and set parameters or otherwise control 
subsequent processing. They begin with a period or an acute accent, 
followed by a 1- or 2-character name that specify a basic request or the 
substitution of a user-defined macro in place of the control line. 

display: A block of text that is to be kept on one page. The relevant 
text is enclosed within the . DS and . DE macros. By default, the text 
lines are not filled or adjusted, but you can override this by providing 
an argument to the . DS macro. 

diversion: A mechanism provided by the trof f formatter to store a 
block of input text for a period of time in order to determine its size and 
whether it will fit on the current page before actually printing it; for 
example, footnotes or text between the macros . KS and . ke that is not 
to be split across a page boundary (as for a figure or table.) 

eqn : A mathematical equation formatting preprocessor for t r o f f 
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that produces typeset-quality mathematical text, eqn converts 
mathematical input into troff commands, and the resulting output is 
passed directly to the formatter for further processing. Mathematical 
expressions are entered by beginning and ending each with the 
delimiters .EQand .EN. In-line equations may be included in text if 
they are enclosed in delimiters which are defined at the beginning of 
the text file. 

escape character: (\), followed by a command name anywhere in a 
line. The escape character introduces sequences that cause the 
following character to mean another character or signals the formatter 
to treat the sequence as a command and not text. It should not be 
confused with the control character ESC of the same name, 

em: Used to specify a width approximately equal to the size of the 
letter m in the current font and point size. 

en: Half of an em. 

field: A string of characters separated fi-om other strings by blanks, 
tabs, or other specific delimiters. 

fill: To place as much text on a line as will fit, regardless of how the 
text occurs in the input file. 

floating keep: Begins with . KF and ends with .ke. If the number of 
lines in a block of text exceeds the remaining lines on the page and it is 
necessary to force a page break, the regular text material continues to 
print until it reaches the end of the page, and the block of text is 
printed. It differs from a static keep in that it waits for a natural page 
break rather than forcing one. 

font: A collection of letters and characters unified by a distinctive 
pattern or "look." Times Roman, for example, is the default font for 

troff. 

footer: A line of text that is printed on the bottom of every page. 
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formatter: A utility that processes text for output to a device. The 
nrof f and trof f utilities, for example, are formatters that justify the 
margins, center the titles, number the pages, and perfomti other 
enhancements that improve the printed appearance of text files. 

grap : A preprocessor for pic which permits inclusion of graphs in a 
document formatted with trof f . Specifications for the graph are 
enclosed within . Gl and . G2 pairs and are translated by grap into 
pic code. 

header: A line of text that is printed on the top of every page. 

ligatures: Two or more characters or letters linked together. Two 
ligatures are available in the trof f character set: fi and fl. They may 
be input (even in the nrof f formatter) by \ ( f i and \ ( f 1, 
respectively. Note that Ugature mode is normally on in the trof f 
formatter; that is, ligatures are automatically produced. 

leader: A single character, repeated as necessary, to visually tie one 
item to another in a text line. For example, a heading and page number 
in a table of contents are often connected with a line of dots. The 
leader character is a period by default and may be set using the ' * . Ic" 
troff request. 

local motion: Vertical and horizontal motion contained within a line. 
The function \v' n' is used for vertical motion and \h' n' can be 
used for horizontal motion. The distance n may be negative; the 
positive directions are rightward and downward. To avoid unexpected 
vertical dislocations, it is necessary that the net vertical local motion 
(within a word in filled text and otherwise within a line) balance to 
zero. 

macros: A collection of instructions or requests invoked by a single, 
simplified command. Text processing macros, for example, are 
embedded in a file and usually take the form JOC, where X is generally 
a capital letter. Each macro is an abbreviation for a collection of 
requests that would otherwise require repetition. 
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macro package: A collection of macros grouped into a useful unit. 

neqn : An nrof f preprocessor which formats mathematical symbols 
and equations using standard keyboard symbols to approximate the 
mathematical symbols requested as closely as possible. 

nrof f : A formatter which produces typewriter-quality output. 

number registers: Where t rof f keeps track of many of the 
parameters governing the page layout. You can create a number 
register with the command . nr or change existing parameters, such as, 
. nr Si 8 to change the standard indent for displays. 

output devices: Typically, a printer or display device, such as a digital 
typesetter or phototypesetter, laser-driven printer, high-resolution video 
display terminal, terminal screen, dot matrix printer, or daisy wheel 
printer. 

output translation: One character can be made a stand-in for another 
character using the . tr request 

page footer: Text printed at the bottom of each page. 

page header: Text printed at the top of each page. 

page offset: The distance betweeen the left margin and the left edge of 
the paper. The default page offset for nrof f/t rof f is one inch. 

pic : A t r o f f preprocessor which produces simple line drawings in 
a document The basic figures are arrow, box, circle, line, arc, ellipse 
and text Descriptions are included between . sps and . pe pairs. 

pica: A measurement (1/6 inch or 6 points) used for specifying line 
lengths and page lengths. 

point size: Used to specify size of type using printer's measurement of 
a point equal to 1/72 of an inch. The default point size for t rof f is 
10-point type. 
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preprocessor: A utility such as tbl and eqn used to translate your 
input into commands that t rof f can understand before piping the 
output to that process. Also the part of a compiler that provides file 
inclusion and macro substitution. 

requests: Built-in commands recognized by the forjnatters. 

static keep: A mechanism for preserving the integrity of a block of 
text Begins with . KS and ends with .KE. If the number of lines 
within these two macros exceeds the remaining lines on the page, a 
page break is forced and the material in the block is printed on the next 
page. 

string: A named group of characters, not including a newline 
character, that may be interpolated by name at any point 

tab leader: A string of repeated characters between a tab stop and the 
next tab or end of line. A column entry followed by \a will repeat the 
leader character to the next entry. The default leader character is a 
period. A different character can be specified with the . ic instruction. 

tbl : A text prep-ocessor to trof f which formats tables. Table 
specifications and text are placed between the commands . TS and 
. TE. Columns can be centered, right adjusted, left adjusted, or aligned 
by decimal points. Headings may be placed over single columns or 
groups of columns. Any table or element can be enclosed in a box and 
vertical and horizontal lines placed at will. 

text line: A line destined to be printed or displayed. 

transparent throughput: An input line beginning with a \ ! is read in 
copy mode and transparently output (without the initial \ ! ); the text 
processor is otherwise unaware of the line's presence. This mechanism 
may be used to pass control information to a post-processor or to 
embed control lines in a macro created by a diversion. 

trap: A mechanism used in writing macros to interrupt processing in 
order to divert to another routine appropriate for the situation. Three 
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types of trap mechanisms are available: page traps, diversion traps, and 
input-line-count traps. 

trof f : A formatter which produces high-quality output on a high 
resolution typesetter or laser printer. 

unpaddable space: A space that cannot be expanded during 
justification. 

vertical spacing: The vertical distance from the base line of one line 
of text to the base line of the next. 

width function: The width function \w' string' generates the numeric 
width of string (in basic units). Size and font changes may be 
embedded in string and will not affect the current environment. 

word: A string of characters bounded at each end by one or more of 
the following: 

• the space character 

• the tab character 

• the beginning of the input line 

• the end of the input line 
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